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About This Manual 


Objectives of This Manual 

This manual provides detailed reference information about the Paris interface to the *Render library 
routines. Separate ^Render manuals are available for the C* and CM Fortran interfaces. 


intended Audience 

This manual is intended for programmers using *Render to support graphics or visualization 
applications on the Connection Machine. 

It is assumed that the reader has a basic understanding of Paris programming on the Connection 
Machine System. 


Revision Information 

This manual documents *Render, Version 2.0. 

This manual replaces the *Render Reference Manual, Version 5.2. 


Organization of This Manual 

Chapter 1 Introduction to ^Render 

A brief overview of the *Render library and its use. 

Chapter 2 Drawing Routines 

Detailed documentation of the *Render point, line, sphere, and array drawing rou¬ 
tines. 

Chapter 3 Graphics Math Routines 

Detailed documentation of the *Render graphics math routines. 

These routines provide utilities for performing common graphics math operations 
on vectors and matrices in front-end arrays or CM fields. 
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Xll 


Chapter 4 Dithering Routines 

♦Render’s halftone routines convert a grayscale image of floating-point or double- 
floating-point values to a 1-bit-per-pixel image suitable for displaying on a black 
and white monitor. In addition, the library includes two routines that convert color 
RGB images to grayscale 


Related Documents 

This manual is one of three that make up the Connection Machine Visualization Programming 
documentation set. The other two are: 

■ Generic Display Interface Reference Manual 

■ Image File Interface Reference Manual 


Notation Conventions 

The table below displays the notation conventions observed in this manual. 


Convention 

Meaning 

bold typewriter 

C/Paris, Fortran/Paris, and Lisp/Paris language elements, such as oper¬ 
ators, keywords, and function names, when they appear embedded in 
text or in syntax lines. Also UNIX and CM System Software com¬ 
mands, command options, and file names. 

italics 

Argument or parameter names and placeholders, when they appear em¬ 
bedded in text or syntax lines. 

typewriter 

Code examples and code fragments. 

% bold typewriter 

typewriter 

In interactive examples, user input is shown in bold typewriter 
and system output is shown in regular typewriter font. 
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Customer Support 


Thinking Machines Customer Support encourages customers to report errors in Connection Machine 
operation and to suggest improvements in our products. 

When reporting an error, please provide as much information as possible to help us identify and 
correct the problem. A code example that failed to execute, a session transcript, the record of a back¬ 
trace, or other such information can greatly reduce the time it takes Thinking Machines to respond 
to the report. 

If your site has an Applications Engineer or a local site coordinator, please contact that person direct¬ 
ly for support. Otherwise, please contact Thinking Machines’ home office customer support staff: 


U.S. Mail: Thinking Machines Corporation 

Customer Support 
245 First Street 

Cambridge, Massachusetts 02142-1264 

Internet 

Electronic Mail: customer-support@think.com 


uucp 

Electronic Mail: ames!think! customer-support 

Telephone: (617) 234-4000 

(617) 876-1111 


For Symbolics Users Only 

The Symbolics Lisp machine, when connected to the Internet network, provides a special mail facil¬ 
ity for automatic reporting of Connection Machine system errors. When such an error occurs, simply 
press Ctrl-M to create a report. In the mail window that appears, the To: field should be addressed 
as follows: 


To: customer-support@think.com 

Please supplement the automatic report with any further pertinent information. 
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Chapter 1 

Introduction to *Render 


The *Render library is a set of Paris-level utilities for drawing simple graphics primitives 
into an image buffer field in the Connection Machine memory. This image may then be 
transferred to an X Window System display or CM framebuffer for display. 

This chapter provides a brief introduction to the *Render library. The remaining chapters 
give full descriptions of the routines. 


1.1 The CM Visualization Libraries 

*Render is one of three libraries that support visualization programming on the CM. The 
other two libraries are the Generic Display Interface and the Image File Interface. 

As illustrated in Figure 1, these three libraries provide the basic tools for building visualiza¬ 
tion applications on the CM. With *Render you can process the data produced by your 
application to create an image in an image buffer in CM memory. With the Generic Display 
Interface you can create and control a display space and write the image buffer to it. Final¬ 
ly, the Image File Interface enables you to store images for future display or processing, 
or to transfer the image to other graphics environments. 

The image buffer is a CM field or variable in a 2D Paris VP set allocated in the size and 
shape of the image to be displayed. The image buffer is used to collect and store pixel 
values for display. Each virtual processor in the image buffer VP set contains a color value 
and, if 3D, a z coordinate for the pixel at the corresponding (x, y) location on the display. 
The image buffer is discussed in detail in the introduction to Chapter 2. 
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1.1.1 The Generic Display Interface 

The Generic Display Interface is a library of routines that provide a single simple interface 
through which your application can 

■ create and initialize Generic Display workstations and displays by having the user 
select them from a menu (the display provides a display space for images from CM 
memory; the workstation provides resources to support text and cursor routines) 

■ transfer image data from CM memory to different types of displays without 
specialized routines 

■ query and modify the characteristics of the physical displays from the Generic 
Display Interface, including the display color maps 

■ display text strings to any selected generic display 
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■ display, track, and interact with a cursor on the generic display with your work¬ 
station mouse 

The Generic Display Interface simplifies image display and interaction and allows you to 
write device-independent applications that can be moved to different displays at run time 
without changing your application. It is documented in the Generic Display Reference 
Manual for Paris included with the CM visualization document set. 


1.1.2 The Image File Interface 

The Image File Interface supports the transfer of images to files in TIFF (Tagged Image 
File Format), a standard specification for image data files. TIFF is supported by many other 
graphics software packages, so you can easily move CM images stored with the Image File 
Interface to other graphics environments for editing or display. The TIFF format also pro¬ 
vides for compression of the image data in the file and stores information about the image 
that can be used when reading the file back into the Connection Machine system or into 
some other TIFF reader. 

The Image File Interface transfers images between files and an image buffer on the CM, 
a scalar array on the front-end computer, or even directly to or from a Generic Display 
Interface display. It is documented in the Image File Interface Reference Manual for Paris. 


1.2 *Render 

*Render is made up of the following major components: 

■ Drawing Routines 

The *Render drawing routines write 2D and 3D points, 2D lines, and image arrays 
into an image buffer field in CM memory. Some routines, those with je_ in their 
names, draw a single point or line specified by coordinates stored in ID arrays on 
the front-end computer. Other routines take a field of coordinates and draw the set 
of lines or points specified in a single operation. 

Simple sphere drawing is also supported by a routine that draws shaded spheres at 
specified locations in the image buffer. 

In addition, *Render includes clipping operations that allow you to clip a set of line 
coordinates in a CM field to a specified clipping range. 
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These routines are described in Chapter 2 of this manual. 

■ Graphics Math Routines 

*Render’s Graphics Math routines support the basic graphics math operations on 
vectors and matrices. As with the drawing routines, there are math routines to oper¬ 
ate on a single vector or matrix in front-end memory, or on a field of vectors or 
matrices in CM memory. 

The vector routines include basic operations such as copying, adding, subtracting, 
normalizing, negating, taking the cosine, dot product, cross product, or perpen¬ 
dicular of two vectors, and applying transformation matrix to a vector. More 
specialized routines include determining reflectance and transmittance vectors for 
ray-tracing and radiosity applications. 

Included with the graphics math routines are color conversion routines to trans¬ 
form color vectors between different color models. 

These routines are described in Chapter 3. 

■ Dithering Routines 

The dithering routines allow you to move a color image to a grayscale or mono¬ 
chrome scale with a minimum loss of image detail. 

Two routines convert a color RGB image to an 8-bit grayscale image. That image 
may then be given to one of a set of 6 dithering images that reduce the grayscale 
to a 1-bit monochrome image. The dithering images support either integer or float¬ 
ing point color values and allow you to apply either dot diffusion or error 
propagation methods to produce the monochrome image. 

These routines are described in Chapter 4. 


1.3 Using ^Render 

To use the *Render routines you must include the appropriate header file in your program 
and link with the supporting libraries when compiling. 
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1.3.1 C/Paris 

To use the *Render drawing and dither routines you must include the header file cmsr- 
draw. h as follows: 

♦include <cm/cmsr-draw.h> 

To use the *Render math routines you must include the header file cmsr-math.h as 
follows: 

♦include <cm/cmsr-math.h> 

For all the *Render routines, you must use the following links when compiling: 
cc prog.c -lcmsr -lxll -lparis -lm 


1.3.2 Fortran/Paris 

To use the *Render drawing and dither routines you must include the header file cmsr- 
draw-f ort. h as follows: 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

To use the ^Render math routines you must include the header file cmsr-math-f ort. h 
as follows: 

INCLUDE '/usr/include/cm/cmsr-math-fort.h , 


Note 

This directory path, /usr/inolude/cm/cmsr-math-f ort. h, 
is the location for these header files recommended by the installa¬ 
tion script for this software. However, you should check with your 
system administrator for the exact location at your site. 


For all the *Render routines, you must use the following links when compiling: 

cc prog.c -lcmsr -lxll -lparisfort -lparis -lm 
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1.3.3 Lisp 

For Lisp programs you must use a band in which the graphics package has been loaded. 
If necessary, you can load it by entering: 

(lcmw:load-optional-system ' graphics) 

This will make all the graphics library functions available. 
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Chapter 2 

Drawing Routines 


2.1 Overview 

Render helps you create and manipulate an image in an image buffer in Connection 
Machine memory. The drawing routines draw points, lines, arrays and spheres into an 
image buffer in CM memory by writing color values into the appropriate locations. 


2.1.1 The Image Buffer Field 

The image buffer is a Paris field in a 2D VP set allocated in the size and shape of the image 
to be displayed. The image buffer is the destination field for the *Render drawing opera¬ 
tions and the source field for the Generic Display Interface’s display routines. 

You allocate the image buffer so that the length of the axes of the image buffer VP set corre¬ 
sponds to the resolution of the image to be displayed, 1 virtual processor to each pixel. Axis 
0 of the geometry maps to the display’s x (horizontal) axis, and axis 1 of the geometry maps 
to the display’s y (vertical) axis. Each virtual processor in the image buffer VP set contains 
a color value and, if 3D, a z coordinate for the pixel at the corresponding (x, y) location on 
the display. 

*Render and the Generic Display Interface allow you to operate on the image buffer like 
a virtual display space by specifying locations in screen coordinates. The visualization li¬ 
braries assume the right-handed screen coordinate system shown in Figure 2. The origin 
(0,0) is at the upper left comer of the image, positive x increases to the right, positive y 
increases toward the bottom of the screen, and positive z increases into the screen. The 
coordinate values are specified in terms of pixels. 
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Figure 2. The image buffer coordinate system. 


The 2D *Render drawing routines specify the location of the drawing primitives in x and 
y coordinate pairs that correspond to pixel/processor locations in the image buffer field. 
The routines “draw” into the image buffer field by loading a specified color value into the 
appropriate processor location. 

The image buffer is then displayed by transferring the color data from CM memory to a 
generic display, as with the Generic Display Interface routine CMSR_write_to_display. 
The origin of the image buffer field (0,0) is displayed at the upper left comer of the display 
and the color value in each virtual processor is assigned to the corresponding pixel of the 
display. The length of the image buffer field allocated for the color data should be the same 
as the depth of the display. If the field length is longer, only the low order, least significant 
bits are displayed. If the field length is shorter than the depth of the window, an error is 
signaled. 


2.1.2 The Z Buffer 

For *Render’s 3D drawing routines, a z-buffer field is allocated containing two subfields, 
one for color data and one for z coordinate data. The z value occupies the most significant 
bits, and the color value occupies the least significant bits. The 3D drawing routines specify 
x, y, and z coordinates, and color values. *Render includes a utility routine, CMSR 
initialize_z_buf f er, which prepares an allocated z-buffer field for use by initializing 
the z coordinate portion of the z-buffer field to the largest value that can be represented and 
the color portion to a specified background color. 
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As with the 2D routines, the x and y coordinates determine the location in the z-buffer field 
VP set that will receive the color value. But before writing the color value, the system per¬ 
forms a z-buffer comparison between the incoming z coordinate and the z-buffer value 
already stored at that location. If the incoming z coordinate is smaller (that is, “nearer” the 
viewer), the color value associated with it is written to the field and the incoming z coordi¬ 
nate becomes the z-buffer value at that point. If the incoming z coordinate is larger (that 
is, “farther” from the viewer) than the current z-buffer value, neither the color nor z coordi¬ 
nate is changed for that location. Thus, the point stored is the visible point nearest the 
viewer. 


2.1.3 Framebuffer-Ordered Geometries 

The transfer of fields of color data between CM memory and the CM framebuffer can be 
optimized by using image buffer geometries created with framebuffer ordering. I/O per¬ 
formance to X Window System or Symbolics generic displays is unaffected by the choice 
of ordering. 

The function CMFB-create-cmfb-geometry allocates and returns a 2D geometry of a 
specified width and height. Width specifies the length of axis 0 of the geometry and maps 
to the screen’s x (horizontal) axis. Height specifies the length of axis 1 and maps to the 
screen’s y (vertical) axis. Both axes are created with framebuffer ordering. 

Framebuffer-ordered geometries are intended to be used only as image buffers. While 
image transfers to the CM framebuffer are faster, Paris NEWS communication functions 
operate much more slowly on a framebuffer-ordered VP set. The NEWS function must per¬ 
form a send to reorder a framebuffer-ordered geometry before the NEWS operation can be 
completed. 

If you do not use NEWS functions in the image buffer, it is recommended that you do not 
use a normal grid-ordered geometry as an image buffer. The Generic Display Interface I/O 
functions will accept a NEWS-ordered geometry as an image buffer, but performance is 
slowed significantly. These operations must perform a send to “shuffle” the field into 
framebuffer order before transferring it to the CM framebuffer. 


2.1.4 The Combiner Parameter 

^Render routines that draw into the image buffer use a combiner parameter to define the 
method used to combine the array values being transferred from the source field with the 
values already in the image buffer field. Valid values for this parameter are: 
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■ DEFAULT 

■ OVERWRITE 

■ LOGIOR 

■ LOGAND 

■ LOGXOR 

■ U-ADD 

■ S-ADD 

■ U—MIN 

■ S—MIN 

■ U-MAX 

■ S-MAX 


No combiner method specified. 

Replace existing image buffer value with source value. 
Combine using bitwise logical inclusive OR. 

Combine using bitwise logical AND. 

Combine using bitwise logical exclusive OR. 

Combine using unsigned integer addition. 

Combine using signed integer addition. 

Combine using unsigned integer minimum operation. 
Combine using signed integer minimum operation. 
Combine using unsigned integer maximum operation. 
Combine using signed integer maximum operation. 


These values correspond to the appropriate versions of the Paris send functions. For exam¬ 
ple, specifying a combiner of U-MAX will call send-with-u-max to write into the image 
buffer. The DEFAULT setting corresponds to the send-lL Paris function. 


Note that the combiner parameter also controls how multiple values sent to the same image 
buffer location are to be combined. For example, if two or more color values are written 
to a single location in the image buffer field and the combiner operation is ADD, each color 
value is added to the current color at that location as it arrives at the processor. If the com¬ 
biner operation is max, the largest of the arriving values or the original value is saved. 


If more than one value is received at a single location when combiner is set to default 
or overwrite, the result is unpredictable. The overwrite operation discards the original 
value, but does not predict which of the incoming values will be saved. The default 
operation overwrites the original value, but an unpredictable ordering of bits will be saved; 
that is, none of the incoming messages will be saved intact. You should use these operations 
only when you are sure that only one value will be sent to any location. 


2.1.5 Drawing Points and Lines 

The 2D point drawing routines load a color value into a specific location in the image buffer 
field. The 3D point drawing routines write to a specific (x, y) location in the z-buffer field 
in the same way as the 2D routines. But the 3D routines also perform a z coordinate com¬ 
parison as described in Section 1.3.2 above. The color value associated with the smaller z 
(“nearer” the viewer) is chosen over the color value with a larger z. The line drawing rou¬ 
tines draw a color value into the image buffer field along a line between specified 
endpoints. 

As summarized in Table 1, different versions of the *Render operations support either 
front-end variables or other Connection Machine fields as the source for coordinate and 


10 


Version 2.0, November 1991 




Chapter 2. Drawing Routines 


color values. Similarly, in different "“Render operations the coordinate and color values can 
be either floating-point or signed integer values. 


Table 1. "“Render point and line drawing operations. 



Uses Front-End Source Variable 

Uses CM Source Field 

Signed 

Integer 

Values 

CMSR_fe_s_draw_line 
CMSR_f e_s__draw_j?oint 

CMSR_s_jir aw__l ine 
CMSR_s_draw_point 

Floating- 

Point 

Values 

CMSR_£e_f_draw_JLine 
CMSR_f e_fjir aw_po in t 
CMSR__fe_f_draw__point_3d 

CMSR_f_dr aw_JL ine 

CMSR_f_draw_point 

CMSR_f_draw__point_3d 


The "“Render operations that use front-end variables specify a single coordinate pair and 
color value. These operations draw a single point or line with each call of the routine. 

The "“Render operations that use CM source fields operate in parallel on the set of coordi¬ 
nate pairs and color values specified in die fields. With each call of these routines, one point 
or line is drawn for each active virtual processor in the current VP set. 

The source fields must be in the current VP set when the "“Render operation is called, but 
the source fields need not be in the same VP set as the image buffer field. 


Floating-Point Coordinates 

Floating-point coordinate values must, of course, be reduced to integer values to determine 
which discrete pixels are actually turned on. 

When using floating-point coordinate values, the "“Render routines round the floating-point 
values to integral pixel values by using the function 

round (value) = floor (value + 0.5) 

This means that the area of a pixel in floating-point coordinates is (jc- 0.5, r+0.5) by 
(y-0.5, y+0.5). For example, the first pixel is lit by the coordinates from ( -.05, -0.5) to 
(0.5,0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, -0.5) 
to (127.5, 127.5). 
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This convention has been adopted because it allows more accurate line drawing. For exam¬ 
ple, if a line is drawn from (0.0, 0.0) to (9.0, 1.0) the pixels that will be lit are as follows: 



If a simple floor function where used, the less intuitive result would be: 



Note 

Line drawing using floating-point coordinates with CMSR_fe_f_ 
draw_line or CMSR_f_draw_line is significantly slower than 
the line-drawing routines that use integer coordinates. If you are 
hampered by the speed of the floating-point routines, you may 
want to convert the coordinates to integer values and then use 
CMSR_fe_s_draw_line or CMSR_s_draw_line. 

The floating-point routines are slower because of added process¬ 
ing needed to draw fractional slopes accurately. 


Clipping 

The *Render line and point drawing operations optionally clip the primitives to the coordi¬ 
nate range of the image buffer field. If the clipjp parameter for these routines is true, points 
and portions of lines with coordinates outside the image buffer field will not be drawn. 
These operations do not change the coordinate values specified by the user in CM source 
fields or front-end variables. 
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In addition, two clipping operations, CMSR_f_clip_lines and CMSR_s_clip_lines, 
clip source fields containing 2D floating-point or integer coordinate values, respectively, 
to a user-defined coordinate range. 

If a line falls completely outside the clipping range, these routines clear the test flag of the 
corresponding virtual processor. If only a portion of a line is within the clipping range, 
these routines set the virtual processor test flag and clip the lines by interpolating new end¬ 
points at the boundary of the clipping range, overwriting the original line coordinates 
specified in the source field. If a line is entirely within the clipping range, these routines 
set the virtual processor test flag and leave the coordinates unchanged. 

You may then use the Paris instruction CM_logand_context_with_test to load the 
test flag values into the context flags of the source field VP set and use these fields as source 
fields for CMSR s draw line or CMSR f draw line. 


2.1.6 Sphere Drawing 

CMSR_s_draw_sphere provides a simple interface for drawing shaded spheres into an 
image buffer in CM memory. 

CMSR_s_draw_sphere takes six CM fields as arguments: 

■ the image buffer field into which the spheres are to be drawn 

■ a vector field specifying the 3D coordinates of each sphere’s center 

■ a field giving the radius of each sphere 

■ two fields giving minimum and maximum color values defining the range of 
values from the color map that the sphere can take on 

■ an optional information field that can be used as you wish. 

The spheres are shaded as if a light source was placed at negative infinity along the z axis, 
and anti-aliasing may be performed to smooth the sphere edges. 


2.1.7 Transferring Image Arrays 

♦Render also includes routines to transfer arrays of image data from one CM field to 
another, and between a front-end array and a CM field. 
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From a CM Field to the Image Buffer 

CMSR_draw_image allows you to transfer a portion of a source field of color values to the 
image buffer field. Both the source field and the image buffer field must be in two-dimen¬ 
sional VP sets. The source field must be in the current VP set when the operation is called. 
The image buffer field does not have to be in the current VP set. 

CMSR_draw_image specifies the coordinates of a subarray of the source field and a loca¬ 
tion in the image buffer. This operation allows you to move a portion of an image into the 
image buffer field from another two-dimensional VP set, or to move a portion of an image 
to another position within an image buffer field. 


Between a Front-End Array and a CM Field 

The following routines use bit-packed transfers to move an image between an array on the 
front-end computer and a field in CM memory. 

The read routines pack image buffer field values into a front-end array: 

CMSR_read_array_from_field 

CMSR_read_array_from_field_l 

These routines pack the image by loading the color values from the image buffer field into 
the front-end array elements as closely as possible. For example, a 128 by 128 1-bit image 
could be packed into a 16 by 128 front-end char or character array, 8 image array 
elements to a front-end array element. When CMSR_read_array_from_field writes 
this image to the front-end array, the image field in 8 CM processors fills a byte of the 
front-end array. If array element size is 8, each CM processor fills a byte of the front-end 
array elements, and if array element size is 32, each CM processor fills a word of the 
front-end array elements. 

The write routines perform the opposite operation, loading an image array packed into a 
front-end array into a CM image buffer field: 

CMSR_write_array_to_field 

CMSR_write_array_to_field_l 

The routines that end in 1 are more detailed versions. They allow you to specify a portion 
of the source (array or field) to be transferred rather than the entire array, and to specify 
offsets indicating where the image array should be placed. 
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2.2 *Render Drawing Routine Descriptions 

This section provides individual descriptions of the *Render drawing routines: 

CMSR_initialize__z_buffer. 17 

CMSR_£_draw_point . 19 

CMSR_f_drawjpoint_3d. 23 

CMSRjs__draw_point . 27 

CMSR_fe_£_draw_jpoint. 30 

CMSR_fe_f_drawjpoint_3d. 33 

CMSR_fe_s_drawjpoint. 37 

CMSR_f_draw_line. 40 

CMSR_js_draw_line. 44 

CMSR_fe_f_draw__line.. . 48 

CMSR_fe_s_draw_line. 52 

CMSR_f_clip_lines . 56 

CMSR_s_clip_lines . 59 

CMSR_s__draw__sphere . 62 

CMSR__draw__image. 66 

CMSR_fe_draw_rectangle . 69 

CMSR_write_array_to__field. 71 

CMSR_write_array_to_field_l . 74 

CMSR_read_array_from_field . 79 

CMSR_jread_array_froxn_field_l . 82 
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CMSRJnitializejz_buffer 


CMSR_initialize_z_buffer 

Initializes a z-buffer field for use. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR_initialize_z_buffer 

{zjufferJield , colorvalue, coordslen , coord_e_len , color Jen) 

CM_field_id_t zjufferJield; 
int color value; 

unsigned int coord s len; 
unsigned int coord e len; 
unsigned int color Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort .h' 

SUBROUTINE CMSRJCNITIALIZE_ZJBUFFER 

& ( zjufferJeld, color value, coord_sJen, coord_eJen, color len) 

INTEGER zjufferJield 
INTEGER color_value 
INTEGER coord_sJen 
INTEGER coord_eJen 
INTEGER color len 


Lisp Syntax 

CMSR: initialize-z-buf f er ( z-buffer-field 

fioptional (color-value 0) (coord-s-len 23) 
( coord-e-len 8) (color-len 8)) 
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CMSR initialize z buffer 


ARGUMENTS 

z_buffer Jield A Paris field identifier, zjufferJield is a CM field with subfields 

for a floating-point z coordinate value and an unsigned integer 
color value. The z value occupies the most significant bits, and the 
color value occupies the least significant bits. 

The total length of the field must be ( coordslen + coord_e_len 
+ 1 + color Jen) where coord s len is the length of the z 
coordinate significand, coordejen is the length of the z 
coordinate exponent, 1 is the sign bit for the z value, and color Jen 
is the length of the color value. 

color value The color value to which the z-buffer is to be initialized. In Lisp 

this parameter defaults to 0. 

coord s len The length, in bits, of the significand of the z coordinate value in 

zjmf-ferJield. 

coord e len The length, in bits, of the exponent of the z coordinate value in 

zjuf-ferJeld. 

color len The length, in bits, of the color value in zjufferJeld. 


DESCRIPTION 

CMSR_initialize_z_buf fer initializes a z-buffer field for use. The z coordinate 
portion of zjufferJeld is initialized to the largest value that can be represented. The 
color portion of zjufferJeld is initialized to color value. 

This function should be used to initialize any zjuffer Jeld before use. 


SEE ALSO 

CMSR_f_draw_point_3d 
CMS R_f e_f_dr aw_p o i n t_3 d 
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CMSR_f_draw_point 


CMSR_f_draw_point 

Draws a set of 2D points into the CM image buffer field using floating-point coordinate 
values. 


SYNTAX 
C Syntax 

♦include <cm/cmsr.h> 
void 

CMSR__f_draw_point {imageJbuffer Jeld, xJeld, yJeld, color Jield, 

coords Jength, coord_e length, color Jength, 
combiner, clip_p) 

imagejbuffer Jieldx Jield, y Jield, color Jield ; 
coordjsjength, coord _eJength, color length ; 
combiner; 
clip_p; 


CM_f i e 1 d_i d___t 
unsigned int 
CMSR_conibiner__t 
int 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_F_DRAW_POINT 

& (image Jbuffer Jield, x Jeld, yjeld,color Jeld, 

& coords Jength, coord ejength, colorJength, 

& combiner, clip_p) 

INTEGER imagejbuffer Jeld, x Jeld, y Jeld, color Jeld 
INTEGER coord_sJength, coord_eJength, color Jength 
INTEGER combiner, clip_p 


Lisp Syntax 

CMSR: f-draw-point (image-bufferJeld x-fleld yjeld color Jeld 

coord-s-length coord-e-length color-length 
&key (combiner : default) (clip-p t)) 
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ARGUMENTS 

imageJufferJield A Paris field identifier. The points are drawn into this field at the 
locations specified by the x Jield andy Jield coordinate pairs. The 
image Juffer Jield must be in a two-dimensional VP set, and may 
or may not be in the same VP set as the color Jield and coordinate 
fields. It need not be in the current VP set. 

xJield, y Jield Paris field identifiers. These fields contain floating-point values 

that are, respectively, the x and y coordinates at which to draw the 
points in the image buffer field, x Jield andy Jield must be in the 
current VP set. 

color Jield A Paris field identifier. This field contains the value drawn into the 

image buffer, color Jield must be in the current VP set. 

coord s length, coord e length 

Unsigned integers specifying the length of the floating-point 
significand and exponent, respectively, in the coordinate values 
used for x Jield and y Jield. 

color length The length, in bits, of the color Jield. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR__de f aul t 

CMSR_default 

:DEFAULT 

CMSR_ove rwr i te 

CMSR__overwri te 

.-OVERWRITE 

CMSR_logior 

CMSR_JLogior 

:LOGIOR 

CMSR_logand 

CMSR__logand 

:LOGAND 

CMSR_logxor 

CMSR__logxor 

:LOGXOR 

CMSR__u___add 

CMSR_u_add 

:U—ADD 

CMSR__s_add 

CMSR_s_add 

:S-ADD 

CMSR__ujniin 

CMSR__u__min 

: U-MIN 

CMSR__s_min 

CMSR__s_jnin 

: S—MIN 

CMSR__u__max 

CMSR__u__max 

:U-MAX 

CMSR_s_max 

CMSR__s__max 

: S-MAX 
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CMSR_f_draw_point 


clip_p A symbol indicating whether the line is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines and points outside the range of the image buffer field 
are not drawn. 

If clip _p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_f_draw_point draws a set of points, defined with floating-point coordinates, 
into the specified image buffer field. 

For each active processor in the current VP set, the value in color Jield is drawn into 
image_buffer Jield at the processor location {x Jield, y Jield]. 

The *Render routines round the floating-point values to integral pixel values by using 
the function 

round(va/we) = floor (value+0 .5) 

This means that the area of a pixel in floating-point coordinates is (r-O.S^+O.S) by 
(y-0.5,y+0.5). For example, the first pixel is lit by the coordinates from (-.05, -0.5) to 
(.5, .5), and a display space of size 128 x 128 has a floating-point extent of (-0.5, 
127.5) x (-0.5, 127.5). 

The value written into each location in the image buffer field is a combination of the 
value of color Jield, the previous value at that location, and the value of any other 
points overwriting the same location. The method used to combine these values is con¬ 
trolled by the combiner parameter. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), points with coor¬ 
dinates outside the range of the image buffer field coordinates are not drawn. If the CM 
safety mode is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), an 
error is signaled if the point is not within the boundaries of the destination image buffer 
field. 
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ERRORS 

The following errors are signaled if the CM safety mode is on. 

It is an error to call CMSR_draw_f_point with 

■ coordinates not within the destination image buffer field if clip_p is false 

■ an imageJoufferJield that is not part of a two-dimensional VP set geometry 

■ a color length that is longer than the length of the image buffer Jield or 
colorJield 

■ color or coordinate fields not in the current VP set 


SEE ALSO 

CMSR_fe_s_draw_point 
CMSR_f e_f_dr aw_po in t 
CMSR_s_draw_point 
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CMSR_f_draw_point_3d 


CMSR_f_draw_point_3d 

Draws a set of 3D points into the CM image buffer field using floating-point coordinate 
values. 

SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR__f_d ra w_j>°int__3d (zjufferJield\ xyzvectorafield, color Jeld, 

coordslen, coordelen, color Jen, clip_p) ; 

CM_field_jLd_t zjufferJield; 

CM__f ield_id__t xyzvectorJield; 

CM__f i e 1 d__id__t colorJeld; 

unsigned int coord s len ; 

unsigned int coord e len ; 

unsigned int color Jen ; 

int clip _p ; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

CMSR__F__DRAW__P0INT_3D ( zjuffer Jieldxyzvector Jield, color Jield, 

& coord s len, coord e len, color len, clip_p) 

INTEGER zjufferJield 
INTEGER xyz_yectorJeld 
INTEGER colorJeld 
INTEGER coordjsjen 
INTEGER coordelen 
INTEGER color Jen 
INTEGER clip_jp 

Lisp Syntax 

CMSR: f - draw-point- 3 d ( z-bufferjeld xyz-vectorjeld color Jeld 

coord-s-len coord-e-len color-len 
Soptional (clip—p t) ) 
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ARGUMENTS 

zjbufferJield 


xyz_vectorJield 


colorJield 
coordsjen 

coord_eJen 

color len 


A Paris field identifier, zjufferJield is a CM field with subfields 
for a floating-point z coordinate value and an unsigned integer 
color value. The z value occupies the most significant bits, and the 
color value occupies the least significant bits. 

The total length of the field must be ( coord s jen + coordejen 
+ 1 + color Jen) where coordsjen is the length of the z 
coordinate significand, coord ejen is the length of the z 
coordinate exponent, 1 is the sign bit for the z value, and color Jen 
is the length of the color value. 

The z subfield may be accessed by using the value CM_add_ 
offset_to_field (zjufferJield, color len) and the color 
subfield may be accessed by using the value zjufferJield. 

A Paris field indentifier specifying the field containing the 
coordinates, in screen coordinate space, of the points to be drawn 
to zjuffer Jield. The x and y coordinates specify the location in 
the zjufferJeld VP set that will receive this processor’s z 
coordinate and color value. 

The coordinates are floating-point values, each having a length of 
{coord_s Jen + coord_e len + 1) bits. The vector field is 
organized so that x occupies the least significant bits, y the 
following bits, and z the most significant bits. The length of the 
entire field is (3 * ( coord s jen + coord_e Jen +1)) 

A Paris field indentifier identifying the field containing the integer 
color values to be drawn into zjuffer Jeld. 

The length, in bits, of the significand of the floating-point values 
in the z subfield of zjufferJeld and the x, y, and z subfields of 
xyz_yectorJeld. 

The length, in bits, of the exponent of the floating-point values in 
the z subfield of zjuffer Jeld and the x, y, and z subfields of 
xyzjyectorJeld. 

The length, in bits, of the color subfield in zjuffer Jeld and the 
colorJeld. 


24 


Version 2.0, November 1991 



Chapter 2. Drawing Routines 


CMSR_f_draw_point_3d 


clip_p A symbol indicating whether the points are to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines, or portions of lines, drawn outside the range of the 
zjbuffer Jield coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the zjufferJield. 

The range of the zjbuffer Jield is defined by the length of the 2 
axes in the 2D geometry in which it is defined. 


DESCRIPTION 

For each active processor in the VP set containing xyz_vectorJield and color Jield, 
CMSR_f_draw_point_3d draws a z-buffer image value into z bufferJield at the 
location specified by the x and y components of the xyzjvectorJield. The z-buffer 
image value is composed of the z value from xyz_vectorJield and the color value from 
colorJield. 

The *Render routines round the floating-point coordinate values to integral pixel 
values by using the function 

round (value) = floor (value + 0.5) 

This means that the area of a pixel in floating-point coordinates is (x - 0.5, x + 0.5) by 
(y - 0.5, y + 0.5). For example, the first pixel is lit by the coordinates from ( -.05, -0.5) 
to (0.5,0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, 
127.5) to (-0.5, 127.5). 

The fields xyz_vector Jield and color Jield must both be in the current VP set when 
CMSR_f_draw_point_3d is called. The field zjuffer Jield does not need to be in 
same VP set as xyz_vectorJield and colorJield, nor does it need to be in the current VP 
set. 

The system performs a z-buffer comparison in zjuffer Jield based on a right handed 
coordinate system, that is, positive z increases into the screen, positive y increases 
toward the bottom of the screen, and positive x increases to the right. The origin of the 
image (0,0) is the upper left comer. If a z-buffer image value is written to a point in 
zjuffer Jeld that already contains an image value, the color value associated with the 
smaller z (“nearer” the viewer) is chosen over the color value with a larger z. 
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ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_f_draw_point_3d 
with 

■ a zjbufferJield that is not part of a two-dimensional VP set geometry 

■ the fields xyz_yectorJield, color Jield not in the current VP set 

■ a color length that is longer than the length of the image Juffer Jield or 
colorJield 

■ coordinates not within the destination z-buffer field if clip_p is false 


SEE ALSO 

CMSR_f e_f_dr aw_p oin t_3d 

CMSR_f_draw_jpoint 

CMSR_s_draw__point 

CMSR_fe_f_draw_point 

CMSR_fe_s_draw_point 
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CMSR_s_draw_point 


CMSR_s_draw_point 

Draws a set of points into the CM image buffer field using signed integer coordinates. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 


void 

CMSR_s_drawjpoint (imageJufferJield, x Jeld, yJeld, color Jeld, 
coordJength, color length, combiner, clip_p) ; 


CM_field_id_t 
unsigned int 
CMSR__combiner_jt 
int 


image JufferJield, xJield, y Jield , co/or Jeld; 
coord Jength, color Jength ; 
combiner ; 
clip_p ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_S_DRAW_POINT 

& (image Juffer Jeld , x Jeld, y Jeld, color Jeld, 

& coord Jength, color Jength, combiner, clip_p) 

INTEGER image JufferJeld, xJeld, yJeld, colorJeld 
INTEGER coord Jength, color Jength, combiner, clip_p 


Lisp Syntax 

CMSR: s-draw-point ( image-buffer Jeld xjeld yjeld 

color Jeld coord-length color-length 
&key (combiner : default) (clip-p t)) 


ARGUMENTS 

image JufferJeld A Paris field identifier. The specified point is drawn into this field 
at the location specified by x Jeld and y Jeld . The image Juffer _ 
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x Jield, y Jield 

colorJield 

coordlength 

color length 
combiner 


clip_p 


field must be in a two-dimensional VP set, and may or may not be 
in the same VP set as the color Jield or coordinate fields. It need 
not be in the current VP set. 

Paris field identifiers. These fields contain integer values that are 
the x and y coordinates, respectively, at which the point is to be 
drawn in the image buffer field, x Jeld andy Jield must be in the 
current VP set. 

A Paris field identifier. This fields contains the value to be drawn 
into the image bufferJeld. color Jeld must be in the current VP 
set. 

An unsigned integer specifying the length of the coordinates used 
for x Jeld and y Jeld. 

NOTE: In routines using signed integer coordinates, coord length 
must include room for the sign bit. 

The length, in bits, of color Jeld. 

A symbol defining the method used to combine the color values 
being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_default 

CMSR__de fault 

:DEFAULT 

CMSR__overwri te 

CMSR_ovGrwjri. t© 

:OVERWRITE 

CMSR_logior 

CMSR_logior 

:LOGIOR 

CMSR_logand 

CMSR_logand 

:LOGAND 

CMSR_logxor 

CMSR__logxor 

:LOGXOR 

CMSR_u_add 

CMSR_u__add 

:U—ADD 

CMSRjs^add 

CMSR_s__add 

:S-ADD 

CMSR__u__min 

CMSR__u__min 

: U-MIN 

CMSR_s_jnin 

CMSR__s_min 

: S—MIN 

CMSR_u_max 

CMSR__u_max 

:U-MAX 

CMSR__s_max 

CMSR__s_max 

: S-MAX 


A symbol indicating whether the point is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), points outside the range of the image buffer field 
coordinates are not drawn. 
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If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_s_draw_point draws a point, defined with signed integer coordinates, into the 
specified image buffer field. 

For each active processor in the current VP set, the value in color Jield is drawn into 
image JmfferJield at processor location (x^y). 

The value written into each location in the image buffer is a combination of the value of 
color Jield, the previous value at that location, and the value of any other points over¬ 
writing the same location. The method used to combine these values is controlled by 
the combiner parameter. 

If clip _p is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), points with coor¬ 
dinates outside the range of the image buffer field are not drawn. If the CM safety mode 
is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), an error is signaled 
if the point is not within the boundaries of the destination image buffer field. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_draw_s_point with 

■ coordinates not within the destination image buffer if clip _p is false 

■ an image JmfferJield that is not part of a two-dimensional VP set geometry 

■ a color length that is longer than the length or the image Jjuffer Jield or 
colorJield 

■ color or coordinate fields not in the current VP set 


SEE ALSO 

CMSR_f_draw_point 

CMSR_fe_s_draw_point 

CMSR_fe_£_draw_point 
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C MSR_fe_f_d raw_poi nt 

Draws a point into the CM image buffer field using front-end floating-point coordinate 
values. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 


void 

CMSR_fe__f__draw_j?oint (imageJbuffer Jield, x, y, color, 

color length, combiner, clip_p) 


CM_field_jL d__t 

double 

int 

unsigned int 

CMSR_combiner_t 

int 


image JbufferJield; 

x,y; 

color; 

colorJength; 
combiner; 
clip_p; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_FEJFJDRAW__P0INT (imageJbuffer Jield, x, y, color, 

color length, combiner, clip p) 

INTEGER imageJufferJeld 

DOUBLE PRECISION X, y 

INTEGER color, color Jength, combiner, clip _p 


Lisp Syntax 

CMSR: fe-f-draw-point (image-buffer Jeld x y color color-length 

&key (combiner : default) (clip-p t)) 
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ARGUMENTS 

image buffer Jield A Paris field identifier. The specified point is drawn into this field 
at the location specified by x and y. The imageJufferJield must 
be in a two-dimensional VP set. It need not be in the current VP 
set. 

x, y Front-end floating-point coordinate values, defining the x and y 

coordinates, respectively, at which to draw the point in the image 
buffer field. 

color Jength The length, in bits, of color. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


Fortran Lisp 

C Values Values Keywords 


CMSR_default 

CMS R_de fault 

DEFAULT 

CMSR_o ve rwr i t e 

CMSR_overwri te 

OVERWRITE 

CMSR_logior 

CMSR^logior 

LOGIOR 

CMSR_logand 

CMSR^JLogand 

LOGAND 

CMSR_logxor 

CMSR_logxor 

LOGXOR 

GMSR _ u _ add 

CMSR__u_add 

U-ADD 

CbtSRjsjaidd 

CMSR__s_add 

S-ADD 

CMSR_u_min 

CMSR__u_min 

U—MIN 

CMSR_s_min 

CMSR__s_min 

S—MIN 

CMSR_u_max 

CMSR__u__max 

U-MAX 

CMSR__s_max 

CMSR_j3_max 

S—MAX 


clip_p A symbol indicating whether the point is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), points outside the range of the image buffer field 
coordinates are not drawn. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 
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DESCRIPTION 

CMSR_fe_f_draw_point draws a point, defined with front-end coordinate values, 
into the specified image buffer field. 

The value in color Jield is drawn into imageJufferJield at processor location (x,y). 
The ^Render routines round the floating-point coordinate values to integral pixel val¬ 
ues by using the function 

round (value) = f loor (value+0. 5) 

This means that the area of a pixel in floating-point coordinates is (x-0.5,x+0.5) by 
(y-0.5,y+0.5). For example, the first pixel is lit by the coordinates from (-.05, -0.5) to 
(0.5, 0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, 
127.5) to (-0.5, 127.5). 

The value written into the location in the image buffer is a combination of the value of 
color Jield , the previous value at that location, and the value of any other points over¬ 
writing the same location. The method used to combine these values is controlled by 
the combiner parameter. 

If clip jp is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), points with coor¬ 
dinates outside the range of the image buffer field coordinates are not drawn. If the CM 
safety mode is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), an 
error is signaled if the point is not within the boundaries of the destination image buffer 
field. 


ERRORS 

With CM safety mode on, an error is signaled if you call C34SR._fe_f_draw_poi.nt 
with 

■ coordinates not within the destination image buffer if clip_p is false 

■ an image JufferJield that is not part of a two-dimensional VP set 

■ a color length that is longer than the length of the image JufferJield 


SEE ALSO 

CMS R_f_dr aw_point 
CMS R_f e_s_dr aw_p o i n t 
CMSR_s_draw_point 
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CMSR_fe_f_draw_point_3d 

Draws a point into the CM image buffer field using 3D front-end floating-point coordinate 
values. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 


void 

CMSR_fe_£_draw_point_3d (zjbuffer Jield, xyzvector, color, 

coord_sJen, coord elen, color Jen, clip_p) 


CM_field_id_t 

double 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
int 


zjbufferJield; 
xyz_vector[ 3] ; 
color; 

coord_s len; 
coord_elen; 
color Jen; 
clip _p ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 


CMSR_FE_F_DRAW__POINT__3D (.zjbuffer Jield , xyz vector , color , 

& coord sjen, coord_eJen, color len, clip_p) 


INTEGER 

DOUBLE PRECISION 

INTEGER 

INTEGER 

INTEGER 

INTEGER 

INTEGER 


zjufferJeld 
xyz_yector (3) 
color 

coordjsjen 
coord_eJen 
color Jen 
clip _p 


Lisp Syntax 

CMSR: fe-f-draw-point-3d (z-buffer Jield xyz-vector color 

coord-s-len coord-e-len color-len 

^optional ( clip-p t)) 
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ARGUMENTS 

zjbufferJield 


xyzjvector 


color 

coordsjen 
coordejen 
color Jen 

clip_p 


A Paris field identifier, zjuffer Jield is a CM field with subfields 
for a floating-point z-coordinate value and an unsigned integer 
color value. The z value occupies the most significant bits, and the 
color value occupies the least significant bits. 

The total length of the field must be ( coordsjen + coord_eJen 
+ 1 + color Jen) where coord_sJen is the length of the 
z-coordinate significand, coordejen is the length of the 
z-coordinate exponent, 1 is the sign bit for the z value, and 
color len is the length of the color value. 

The z subfield may be accessed by using the value 
CM_add_o f f s e t_to_f i e 1 d(zjufferJield, color len) and the 
color subfield may be accessed by using the value zjuffer Jield. 

An array of three double-precision floating-point values on the 
Connection Machine’s front-end computer. The values represent 
the x, y, and z coordinates, respectively, of the point to be drawn 
into the zjuffer Jield in Connection Machine memory. The x and 
y coordinates specify the location in the zjufferJield VP set that 
will receive the z coordinate value and the color value. 

An unsigned integer containing the color value to be drawn to this 
point in zjuffer Jield. The number of bits used to represent the 
color depends on the bits per pixel to be displayed. 

The length, in bits, of the significand of the floating-point values 
in the z subfield of zjufferJeld. 

The length, in bits, of the exponent of the floating-point values in 
the z subfield of zjufferJeld. 

The length, in bits, of the color subfield in zjuffer Jeld. This 
value specifies how many of the least significant bits of color to 
transfer to CM. 

A symbol indicating whether the points are to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines, or portions of lines, drawn outside the range of the 
z-buffer field coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the zjufferJeld. The range 
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of the zjufferJield is defined by the length of the 2 axes in the 
2D geometry in which it is defined. 


DESCRIPTION 

CMSR_fe_f_draw_point_3d draws a z-buffer image value into zjufferJield at the 
location specified by the x and y components of the xyzjyectorJield. The z-buffer 
image value is composed of the z value from xyzjvector Jield and the color value from 
the color argument. 

The *Render routines round the floating-point coordinate values to integral pixel 
values by using the function 

round (value) = floor (value+0. 5) 

This means that the area of a pixel in floating-point coordinates is (x-0.5,x+0.5) by 
(y-0.5,7+0.5). For example, the first pixel is lit by the coordinates from ( -.05, -0.5) to 
(0.5, 0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, 
127.5) to (-0.5, 127.5). 

The system performs a z-buffer comparison in zjufferJield based on a right handed 
coordinate system, that is, positive z increases into the screen, positive y increases 
toward the bottom of the screen, and positive x increases to the right. The origin of the 
image (0,0) is the upper left comer. If a z-buffer image value is written to a point in 
z juffer Jield that already contains an image value, the color value associated with the 
smaller z (“nearer” the viewer) is chosen over the color value with a larger z. 


ERRORS 

With CM safety mode on, an error is signaled if you call OMSR_f e_f_drawjpoint_ 
3d with 

■ coordinates not within the destination image buffer if clip-p is false 

■ a zjuffer Jield that is not part of a two-dimensional VP set 

■ a color Jength that is longer than the length of the color component of 
zjufferJeld 


Version 2.0, November 1991 


35 



CMSR_fe_f_draw_pointJ3d 


*Render Reference Manual for Paris 


SEE ALSO 

CMSR__fj± r awjp°int_3d 
CMSR_f__d r aw_p° ill t 
CMSR_ s __d ra w_j>°i n t 
CMSR_fe_f_draw_point 
CMSR__f e_js_dr awjpoin t 
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CMSR_fe_s_draw_point 

Draws a point into the CM image buffer field using front-end signed integer coordinate 
values. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr. h> 


void 

CMSR_fe_s_draw_point (image buffer Jield, Jt, y, color, 

color length, combiner, clip_p) 


CM__f i e 1 d__i d__ t 
int 

unsigned int 

CMSR__combiner_t 

int 


image JufferJield; 
x, y, color; 
color length; 
combiner; 
clip _p; 


Fortran Syntax 

INCLUDE f /usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR__FE_S__DRAW__POINT (image Juffer Jield, x, y, color, 
& color length, combiner, clipj)) 

INTEGER image Juffer Jield x, y, color, color Jength 
INTEGER combiner 
INTEGER clip _p 


Lisp Syntax 

CMSR: fe-s-draw-point ( image-buffer Jield x y color color-length 

&key (combiner : default) (clip-p t)) 
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ARGUMENTS 

imageJbufferJield A Paris field identifier. The specified point is drawn into this field 
at the location specified by x and y. The image JbufferJield must 
be in a two-dimensional VP set. It need not be in the current VP 
set. 

Front-end integer coordinate values, defining the jc and y 
coordinates, respectively, at which to draw the point in the image 
buffer field. 

An unsigned integer containing the color value to be drawn to this 
point in zjuffer Jield. The number of bits used to represent the 
color depends on the bits per pixel to be displayed. 

color length The length, in bits, of color. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_de fault 

CMS R__de fault 

:DEFAULT 

CMSR_overwri te 

CMSR__ove rwr i t e 

:OVERWRITE 

CMSR_logior 

CMSR_logior 

:L06I0R 

CMSR_JLogand 

CMSR__logand 

:LOGAND 

CMSR_logxor 

CMSR_logxor 

:LOGXOR 

CMSRjajstdd 

CMSR_u_add 

:U—ADD 

CMS R_s_add 

CMSR_s_add 

:S—ADD 

CMSR__u__min 

CMSR_u_min 

: U—MIN 

CMSR___s__min 

CMSR_s__min 

: S—MIN 

CMSR_u__max 

CMSR_ujmax 

:U—MAX 

CMSR_sjmax 

CMSR_s_max 

:S-MAX 


clip_p A symbol indicating whether the point is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), points outside the range of the image buffer field 
coordinates are not drawn. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


x,y 


color 
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DESCRIPTION 

CMSR_fe_s_draw_point draws a point, defined with front-end coordinate values, 
into the specified image buffer field. 

The value in colorJield is drawn into imageJmfferJield at the processor location 


The value written into the location in the image buffer is a combination of the value of 
color Jield, the previous value at that location, and the value of any other points over¬ 
writing the same location. The method used to combine these values is controlled by 
the combiner parameter. 

If clip jp is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), points drawn with 
coordinates outside the range of the image buffer field coordinates are clipped. If the 
CM safety mode is on and clip _p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), 
an error is signaled if the point is not within the boundaries of the destination image 
buffer field. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_fe_s_draw_point 
with 

■ coordinates not within the destination image buffer if clip_p is on 

■ an image_buffer Jield that is not part of a two-dimensional VP set 

■ a color length that is longer than the length of the image buffer Jield or 
colorJield. 


SEE ALSO 

CMS R_f_dr aw_p oint 
CMS R_fe_f_draw_p oint 
CMS R_s_dr aw_p oint 
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CMSR_f_draw_line 

Draws a set of lines into a CM image buffer field using floating-point coordinates. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 


void 

CMSR_f_<draw_line (imageJufferJield, xjstart Jield, yjtartJeld, 

x_end Jield, y_endJield\ color Jield, coordjsjength, 
coord e length, color length, combiner, 
draw end_point_p, clip_p) 


CM field id t 


unsigned int 

CMSR_combiner 

int 


image Juffer Jield, color Jield, 

xjstart Jield, yjtart Jield, 

x_endJeld,y_endJield; 

color length, coord s length,coord_e length ; 

combiner; 

draw end_point_p, clipjp; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_FJDRAW_LINE 

& image JufferJeld, xstartJeld, yjstartJield, xendJield, yendJield, 
& color Jeld, coordjjength, coord ejength, color length, 

& combiner, drawjendj?ointjp, clip_p) 

INTEGER image JufferJeld, colorJeld 
INTEGER xjstart Jeld, yjstart Jeld, x_end Jeld, y_end Jeld 
INTEGER colorJength, coordjjength, coordjejength combiner 
INTEGER draw_endjpointjp, clip_p 


Lisp Syntax 

CMSR: f-draw-line ( image-buffer Jeld x-start-field y-start-field x-end-field 

y-endjeld color Jeld coord-s-length coord-e-length 
color-length &key (combiner : default) 
(draw-end-point-p t) (clip-p t)) 
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ARGUMENTS 

imageJufferJield A Paris field identifier. The specified lines are drawn into this field 
at the locations specified by the (. xstartJield, y_startJield) and 
( xendJield, y_end Jeld) coordinate pairs. The image Juffer_ 
field must be at least as long as color length. The image_buffer_ 
field must be in a two-dimensional VP set, and may or may not be 
in the same VP set as the color Jeld and coordinate fields. 

x start Jield, y startJield 

Paris field identifiers. These fields contain floating-point values 
that are the x and y coordinates, respectively, at which to begin 
drawing the lines. These fields must be in the current VP set. 

x end Jield, y_end Jeld 

Paris field identifiers. These fields contain floating-point values 
that are the x and y coordinates, respectively, at which to end the 
lines. These fields must be in the current VP set. 

color Jeld A Paris field identifier. This field contains the value drawn into the 

image buffer. The color Jeld must be in the current VP set. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMS R_de fault 

CMSR_default 

.•DEFAULT 

CMSR_overwr i te 

CMSR_ove rwr i te 

:OVERWRITE 

CMSR_logior 

CMSR_logior 

:L06I0R 

CMSR_logand 

CMSR_logand 

:LOGAND 

CMSR_logxor 

CMSR__logxor 

:LOGXOR 

CMSRji^add 

CMSR_u__add 

:U—ADD 

CMSR _ s « add 

CMSR__s__add 

:S—ADD 

CMSR__u_jnin 

CMSR_u_min 

: U-MIN 

CMSR__s_jnin 

CMSR__s__min 

: S—MIN 

CMSR_u_max 

CMSR__u_max 

: U-MAX 

CMSR__s__max 

CMSR__s_max 

: S—MAX 
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coordjsjength, coord_e_length 

Unsigned integers specifying the length of the floating-point 
significand and exponent, respectively, in the coordinate values 
used for x_startJield,y_startJeld,x_endJield, andy endJield. 

color length The length, in bits, of the color Jield. 

drow end_point_p A symbol indicating whether the end points of the lines ( x_end_ 
field, y_endJield) are to be drawn or not. The end points are only 
drawn if draw_end_point_p is true (.TRUE, in Fortran, non-NULL 
in C, non-nil in Lisp). 

clip_p A symbol indicating whether the lines are to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines, or portions of lines, drawn outside the range of the 
image buffer field coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_f_draw_line draws a set of lines, defined with floating-poing coordinates, 
into the specified image buffer field. 

For each active processor in the current VP set, the value in color Jield is drawn into 
the image bufferJield at the processor locations along the line from the (x start Jield, 
y_start Jield) to ( x_end Jield, y_end Jield). The starting points of the lines are always 
drawn; the end points are only drawn if draw end_point_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp). 

The *Render routines round the floating-point coordinate values to integral pixel 
values by using the function 

round (value) = floor {value+0 .5) 

This means that the area of a pixel in floating-point coordinates is (x-0.5, x+0.5) by 
(y-0.5, y+0.5). For example, the first pixel is lit by the coordinates from (-.05, -0.5) to 
(0.5, 0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, 
127.5) to (-0.5, 127.5). 

The value written into each location in the image buffer is a combination of the value of 
color Jeld, the previous value at that location, and the value of any other lines writing 
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to the same location. The method used to combine these values is controlled by the 
combiner parameter. 

If the CM safety mode is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in 
Lisp), an error is signaled if a line is not within the boundaries of the destination image 
buffer field. If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), lines, 
or portions of lines, drawn outside the range of the image buffer field coordinates are 
clipped. 


Note 

Line drawing using floating-point coordinates with CMSR_f e_f_ 
draw_line or CMSR_f_draw_line is significantly slower than 
the line drawing routines that use integer coordinates. If you are 
hampered by the speed of the floating-point routines, you may 
want to convert the coordinates to integer values and then use 
CMSR fe s draw line or CMSR s draw line. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_draw_f_line with 

■ coordinates not within the destination image buffer if clip _p is false 

■ an imagebufferJield that is not part of a two-dimensional VP set 

■ a color length that is longer than the length of the image buffer Jield or 
colorJeld 

■ color or coordinate fields that are not in the current VP set 


SEE ALSO 

CMS R_f e_s_dr aw__l i n e 
CMSR_fe_f_draw_line 
CMSR s draw line 
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CMSR_s_draw_line 

Draws a set of lines into the CM image buffer field using signed integer coordinate values. 

SYNTAX 
C Syntax 

♦include <cm/cmsr.h> 
void 

CMSR_s__draw__line (image buffer Jeld,xjstartJeld, yjstartJield 

xjendJield, y_end Jield, color Jield, coord length, 
color lengthy combiner, draw_endjpointjp, clipjp) 

image Juffer Jield, color Jield, x_start Jield, 
yjstartJield ; 

xjend Jield, y end Jield, color Jield; 
coord length, color length ; 
combiner ; 

draw_end_point j>, clipjp ; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_SJDRAW_LINE 

(image JufferJeld,x_startJield, yjstartJeld, 

& x end Jeld, y_end Jeld, color Jeld, coord length, 

& color Jength, combiner, draw endjpointjp, clip_p) 

INTEGER image JufferJeld, xjstartJeld, yjstartJeld 
INTEGER x_end Jeld, yjend Jeld, color Jield 
INTEGER coord Jength, color Jength 
INTEGER combiner 
INTEGER draw endjpointjp, clip jp 

Lisp Syntax 

CMSR: s-draw-line ( image-buffer Jeld x-start-field y-start-field x-end-field 

y-end-field color-field coord-length color-length 
&key (combiner : default) (draw-end-point-p t) 
(clip-p t)) 


CM_field_id_t 

CM_field_id_jt 
unsigned int 
CMSR_combiner_t 
int 
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ARGUMENTS 

imageJtufferJield A Paris field identifier. The specified lines are drawn into this field 
at the locations specified by the {x startJield, y_startJield) and 
( x_end Jield, y_endJield) coordinate pairs. The image_buffer_ 
field must be at least as long as color length. The image buffer_ 
field must be in a two-dimensional VP set, and may or may not be 
in the same VP set as the color Jield and coordinate fields. It need 
not be in the current VP set. 

xstartJield, y_startJield 

Paris field identifiers. These fields contain integer values that are 
the x and y coordinates, respectively, at which to begin drawing 
the lines. These fields must be in the current VP set. 

x end Jield, y_endJield 

Paris field identifiers. These fields contain integer values that are 
the jc and y coordinates, respectively, at which to end the lines. 
These fields must be in the current VP set. 

A Paris field identifier. This field contains the value drawn into the 
image buffer, color Jield must be in the current VP set. 

A symbol defining the method used to combine the color values 
being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


colorJield 

combiner 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_de fault 

CMSR_de fault 

:DEFAULT 

CMSR_overwri te 

CMSR__overwr i te 

:OVERWRITE 

CMSR_logior 

CMSR_logior 

:LOGIOR 

CMSR_logand 

CMSR_logand 

:LOGAND 

CMSR_logxor 

CMSR_logxor 

:LOGXOR 

CMSR_u_add 

CMSR_u__add 

:U—ADD 

CMSR__ s __add 

CMSR_s_add 

:S-ADD 

CMSR_u__min 

CMSR_u_min 

: U-MIN 

CMSR__s_min 

CMSR__s_min 

: S—MIN 

CMSR_u_max 

CMSR_u_max 

:U-MAX 

CMSR_sjmax 

CMSR_s_max 

:S-MAX 


color length The length, in bits, of the color Jield. 
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coord Jength An unsigned integer specifying the length of the coordinates used 

for x_startJield, y_startJield , x_endJield, and y_endJield. 

Note: In routines using signed integer coordinates, coord Jength 
must include room for the sign bit. 

drawendjpoint_p A symbol indicating whether the end point of the line 
( x_end Jield, y_endJield) is drawn or not. The end point is only 
drawn if draw end_point_p is true (.TRUE, in Fortran, non-NULL 
in C, non-nil in Lisp). 

clip_p A symbol indicating whether the line is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines or portions of lines drawn outside the range of the 
image buffer field coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_s_draw_line draws lines, defined with signed integer coordinates, into the 
specified image buffer field. 

For each active processor in the current VP set, the value in color Jield is drawn into 
imageJufferJield at the processor locations along the line from ( x start Jield, 
ystartJeld) to ( xendJield, y_endJield). The start points of the lines are always 
drawn; the end points are only drawn if draw_end_point_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp). 

The value written into each location in the image buffer is a combination of the value of 
color Jeld, the previous value at that location, and the value of any other lines over¬ 
writing the same location. The method used to combine these values is controlled by 
the combiner parameter. 

If the CM safety mode is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in 
Lisp), an error is signaled if the line is not within the boundaries of the destination 
image buffer field. If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines or portions of lines drawn outside the range of the image buffer field coor¬ 
dinates are clipped. 
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ERRORS 

With CM safety mode on, an error is signaled if you call CMSR__draw__s_line with 

■ coordinates not within the destination image buffer if clip_p is false 

■ an image_buffer Jield that is not part of a two-dimensional VP set 

■ a color length that is longer than the image Jbuffer Jield or color Jield 

■ color or coordinate fields not in the current VP set 


SEE ALSO 

CMSR_f__dr aw__l i ne 
CMSR__f e_s__dr aw__l i ne 
CMSR fe f draw line 
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CMSR_fe_f_draw_line 

Draws a line into the CM image buffer field using front-end floating-point coordinate 
values. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 


void 

CMSR_£e_f_draw_line (image Jbuffer Jield, x_start, y_start, 

x_end, y_end, color, color length, combiner, 
draw_end_point_p, clip_p) 


CM_field__id_t 

double 

int 

unsigned int 

CMSR_combiner__t 

int 


imageJbufferJield; 

x_start, y start, x_end, y_end; 

color; 

color length; 
combiner; 

draw_end_point_p, clip_p; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_FE_FJ)RAW_LINE 

& (image JufferJield, xjstart, y start, 

& x end, y_end, color, color length, combiner, 

& draw_end_point_p, clip_p) 

INTEGER imageJmfferJield 

DOUBLE PRECISION x_start, yjstart, x_end, y_end 

INTEGER color, color Jength, combiner draw_endjpoint_p 

INTEGER clip jp 


Lisp Syntax 

CMSR: fe-f-draw-line (image-bufferJield x-start y-start x-end 

y-end color color-length 
&key (combiner -.default) 
(draw-end-point-p t) (clip-p t) 
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ARGUMENTS 

image Jmffer Jield A Paris field identifier. The specified line is drawn into this field 
at the location specified by (x_start, ystart) and (jc end, yend). 
The imageJufferJield must be in a two-dimensional VP set. It 
need not be in the current VP set. 

jc start, y start Front-end floating-point coordinate values, defining the jc and y 
coordinates, respectively, at which to begin drawing the line in the 
image buffer field. 

jc end, y end Front-end floating-point coordinate values, defining the jc and y 
coordinates, respectively, at which to end the line in the image 
buffer field. 

color The value to be drawn into the image JufferJield. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_de fault 

CMSR_default 

DEFAULT 

CMSR_ove rwr i te 

CMSR__overwr i te 

OVERWRITE 

CMSR__logior 

CMSR_logior 

LOGIOR 

CMSR_logand 

CMSR_logand 

LOGAND 

CMSR_logxor 

CMSR_logxor 

: LOGXOR 

CMSR_u_add 

CMSR_u_add 

:U—ADD 

CM SR_ s __ add 

CMSR_s_add 

: S—ADD 

CMSR__u_jnin 

CMSR_u_min 

: U—MIN 

CMSR__s__min 

CMSR__s_min 

: S—MIN 

CMSR_u_max 

CMSR_u_max 

:U-MAX 

CMSR__s_max 

CMSR___s_max 

: S-MAX 


color length The length of color in number of bits. 

drawend_point_p A symbol indicating whether the end point of the line ( x_end , 
y_end) is drawn or not. The end point is only drawn if 
draw end_point_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp). 
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clip_p A symbol indicating whether the line is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines, or portions of lines, drawn outside the range of the 
image buffer field coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_fe_f_draw_l ine draws a line, defined with front-end floating-point coordi¬ 
nate values, into the specified image buffer field. 

The value in color is drawn into the image buffer Jield at the processor locations along 
the line from (; x start , y_start ) to ( xend , yend). The start point is always drawn; the 
end point is only drawn if draw end_point_p is true (.TRUE, in Fortran, non-NULL in 
C, non-nil in Lisp). 

The *Render routines round the floating-point coordinate values to integral pixel val¬ 
ues by using the function 

round (value) = floor (value+0 .5) 

This means that the area of a pixel in floating-point coordinates is (jc- 0.5, r+0.5) by 
(y- 0.5, >>+0.5). For example, the first pixel is lit by the coordinates from ( -.05, -0.5) to 
(0.5, 0.5), and a display space of size 128 by 128 has a floating-point extent of (-0.5, 
127.5) to (-0.5, 127.5). 

The value written into each location in the image buffer is a combination of the value of 
color, the previous value at that location, and the value of any other lines overwriting 
the same location. The method used to combine these values is controlled by the com¬ 
biner parameter. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), lines, or portions 
of lines, drawn outside the range of the image buffer field coordinates are clipped. If 
the CM safety mode is on and clip_p is false (.FALSE, in Fortran, NULL in C, nil in 
Lisp), an error is signaled if the line is not within the boundaries of the destination 
image buffer field. 
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Note 

Line drawing using floating-point coordinates with CMSR_f e_f_ 
draw_line or CMSR_f_draw_line is significantly slower than 
the line drawing routines that use integer coordinates. If you are 
hampered by the speed of the floating-point routines, you may 
want to convert the coordinates to integer values and than use 
CMSR fe s draw line or CMSR s draw line. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_f e_f_draw_line with 

■ coordinates not within the destination image buffer field if clip_p is false 

■ an image Jbuffer Jield that does not have a two-dimensional VP set geometry 

■ a color Jength that is longer than the length of the imageJoujferJield or color 

■ color or coordinate fields (x_start, y_start , x end, y_end, or color) are not 
in the current VP set 


SEE ALSO 

CMSR_f_draw_l ine 
CMS R_f e_s_dr aw_line 
CMSR s draw line 
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CMSR_fe_s_drawJine 

Draws a line into the CM image buffer field using front-end signed integer coordinate 
values. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR__fe__s__draw__l ine 

(imageJbuffer Jield, xjstart, yjstart, xend, y_end, color, 
color length, combiner, drawendjointj, clip_p); 

image JufferJield; 
xjstart, y_start, x_end , y_end, color; 
color length; 
combiner; 

draw end_point_p, clip_p; 


CM__f ield_id_t 
int 

unsigned int 

CMSR_combiner__t 

int 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-draw-fort.h' 


& 

& 

& 


SUBROUTINE CMSR_FE__S_DRAW__LINE 

(imageJuffer Jield, xjstart, yjstart, xjend, 
y_end, color, color length, combiner, 
drawjendjpointjp, clipjp) 


INTEGER imageJufferJield 

INTEGER xjstart, yjstart, x_end, y_end, color, color Jength 
INTEGER combiner, drawjend joint j, clip j 


Lisp Syntax 

CMSR: fe-s-draw-line ( image-buffer Jield x-start y-start x-end 

y-end color color-length 
&key (combiner : default) 
(draw-end-point-p t) (clip-p t) 
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ARGUMENTS 

imageJufferJield A Paris field identifier. The specified line is drawn into this field 
at the location specified by (xstart, y start ) and ( x_end , yend). 
The image Juffer_ field must be in a two-dimensional VP set. It 
need not be in the current VP set. 

x start, y start Front-end integer coordinate values, defining the x and y 
coordinates, respectively, in the image buffer field at which to 
begin drawing the line. 

x end, y end Front-end integer coordinate values, defining the x andy 
coordinates, respectively, in the image buffer field at which to end 
the line. 

color The value to be drawn into the image JufferJield. 

combiner A symbol defining the method used to combine the color values 

being written into the image buffer field with the values already 
in the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_default 

CMSR_default 

DEFAULT 

CMS R_o ve rw r i te 

CMSR__ove rwr i te 

OVERWRITE 

CMSR_logior 

CMSR_logior 

LOGIOR 

CMSR__logand 

CMSR_logand 

LOGAND 

CMSR_logxor 

CMSR__logxor 

LOGXOR 

CMSR__u_ad d 

CMSR^ujidd 

U-ADD 

CMSR__s_add 

CMSR_s_add 

S-ADD 

CMSR_u__min 

CMSR_ji_niin 

U—MIN 

CMSR_s_min 

CMSR__s_min 

S—MIN 

CMSR_u_max 

CMSR_u_max 

U-MAX 

CMSR_s_max 

CMSR__s_max 

S—MAX 


color Jength The length, in bits, of color that is to be transferred to the image_ 

bufferJield. 

drawendjpoint_p A symbol indicating whether the end point of the line (x end, 
y_end) is drawn or not. The end point is only drawn if 
draw end_point_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp). 
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clip_p A symbol indicating whether the line is to be clipped or not. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in 
Lisp), lines, or portions of lines, drawn outside the range of the 
image buffer field coordinates are clipped. 

If clip_p is false (.FALSE, in Fortran, NULL in C, nil in Lisp), it is 
an error to draw outside the range of the image buffer field. 


DESCRIPTION 

CMSR_fe_s_draw_line draws a line, defined with front-end signed integer coordi¬ 
nate values, into the specified image buffer field. 

The value in color is drawn into the imageJmfferJield at the processor locations along 
the line from (x_start Jield, y startJield) to (x end Jield,yendJield). The start point 
is always drawn; the end point is only drawn if draw end_point_p is true (.TRUE, in 
Fortran, non-NULL in C, non-nil in Lisp). 

The value written into each location in the image buffer is a combination of the value of 
color, the previous value at that location, and the value of any other lines overwriting 
the same location. The method used to combine these values is controlled by the com¬ 
biner parameter. 

If clip_p is true (.TRUE, in Fortran, non-NULL in C, non-nil in Lisp), lines, or portions 
of lines, drawn outside the range of the image buffer field coordinates are clipped. If 
the CM safety mode is on and clip _p is false (.FALSE, in Fortran, NULL in C, nil in 
Lisp), an error is signaled if the line is not within the boundaries of the destination 
image buffer field. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_f e_s_draw_line with 

■ coordinates not within the destination image buffer field if clip_p is false 

■ an image Juffer Jield that does not have a two-dimensional VP set geometry 

■ a color Jength that is longer than the length of the image Juffer Jield or color 

■ fields not in the current VP set 
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SEE ALSO 

CMSR_f__draw__line 
CMSR__f e__f__dr aw__l ine 
CMSR s draw line 
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CMSR_f_clipJines 

Clips floating-point line coordinates to specified boundaries. 

SYNTAX 
C Syntax 

♦include <cm/cmsr. h> 
void 

CMSR_f_clip_lines 

(xstartJield, yjstart Jield, xendJeld, y__end Jeld, 
xjnin, yjnin, xjnax, yjnax, coord_sjength, 
coordejength) 

CM_field_id_t xjstartJield, yjstartJield, xendJeld, y_endJeld; 
double xjnin, yjnin, xjnax, yjnax ; 

unsigned int coord sjength, coord ejength ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_F_CLIP_LINES 

(x_startJeld,y_startJeld,x_endJeld, 
y_end Jeld, xjnin, yjnin, xjnax, yjnax, 
coordjsjength, coord_ejength) 

INTEGER x start Jield, yjtart Jeld, x_end Jeld,y_end Jield 

DOUBLE PRECISION xjnin, yjnin, xjnax, yjnax 
INTEGER coord_sjength, coordjejength 


Lisp Syntax 

CMSR: f-clip-lines (x-start-Jield y-start-field x-endjeld y-endjeld 

x-min y-min x-max y-max coord-s-length 
coord-e-length) 


& 

& 

& 
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ARGUMENTS 

x_startJield, yjstartJield 

Paris field identifiers. These fields contain floating-point values 
that are the x and y coordinates, respectively, of the beginning of 
the lines to be clipped. These fields must be in the current VP set. 

xendJield, y end Jield 

Paris field identifiers. These fields contain floating-point values 
that are the x and y coordinates, respectively, of the end of the lines 
to be clipped. These fields must be in the current VP set. 

x_min, yjnin Floating-point coordinates, given as front-end values, specifying 
the lower boundary of the clipping range. 

xjnax, yjnax Floating-point coordinates, given as front-end values, specifying 
the upper right comer of the clip range bounding box. 

coord s length, coord_e length 

Unsigned integers specifying the length of the floating-point 
significand and exponent, respectively, in the coordinates used for 
x start Jield, yjstartJield, x endJield, and yjendJield. 


DESCRIPTION 

CMSR_f_clip_lines clips the line coordinates in the fields xstartJield, 
y_start Jield, x endJield, and y end Jield to the clipping range defined by xjnin, 
yjnin, xjnax, and yjnax. These fields may then be used in a call to CMSR_f_draw_ 
line to draw the clipped set of lines into a CM image buffer. 

CMSR_f_clip_line s modifies the line coordinate fields as follows: 

■ If a line falls completely outside the clipping range, this routine clears the test 
flag of the virtual processor containing that line’s coordinates. 

■ If only a portion of a line falls within the clipping range, this routine sets the 
virtual processors’ test flag and clips the out-of-range coordinates to the edge 
of the clipping box. To clip a line, this routine interpolates new endpoints for 
the line segment and overwrites the fields x startJield, yjstart Jield, 
x end Jeld, and y_end Jeld for that line. 

■ If the line falls completely within the clipping range, the routine sets the virtual 
processors’ test flag and leaves the line coordinates unchanged. 
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NOTE: Before using these clipped fields as source fields for CMSR_f_draw_line, you 
must use the Paris instruction CM_logand_context_with_test to load the context 
flags of the coordinate fields’ VP set with the modified test flag values. (See the Paris 
Reference Manual and Getting Started in C/Paris Programming, Chapter 4, for more 
information.) 


ERRORS 

With CM safety turned on, an error is signaled if xjnin is not less than or equal to 
xjnax and y_min is not less than or equal toy max. 


SEE ALSO 

CMSR_s_c1ip_line s 
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CMSR_s_clipJines 

Clips and/or interpolates signed integer line coordinates to specified boundaries. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_s_clip_lines 

(xstartJield, y_startJeld, x end Jeld, y__end Jield\ 
x_min, yjnin, xjnax, yjnax, coord length) 

CM__field._jLd._jt x start Jield, y startJield, x end Jield, y_end Jield; 
int xjnin, yjnin, xjnax, yjnax ; 

unsigned int coordJength ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw~fort.h' 

SUBROUTINE CMSR__S__CLIP_LINES 

(xjstart Jield, y_start Jield, x_end Jield, 
y_endJield\ xjnin, yjnin, xjnax, yjnax, 
coord Jength) 

INTEGER x start Jield, yjstart Jeld, xjend Jeld, yjend Jeld 
INTEGER xjnin, yjnin, xjnax, yjnax 
INTEGER coord Jength 


Lisp Syntax 

CMSR:s-clip-lines 

(jc -startJeld y-start-field x-endjeld y-endjeld x-min 
y-min x-max y-max coord-length) 


& 

& 

& 
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ARGUMENTS 

xjstartJield, y_startJield 

Paris field identifiers. These fields contain signed integer values 
that are the x and y coordinates, respectively, of the beginning of 
the lines to be clipped. These fields must be in the current VP set. 

x_endJield, y_endJield 

Paris field identifiers. These fields contain signed integer values 
that are the jc and y coordinates, respectively, of the end of the lines 
to be clipped. These fields must be in the current VP set. 

xjnin, yjnin Integer coordinates, given as front-end values, specifying the 
lower bounds of the clipping range for the x and y coordinates. 

xjnax, yjnax Integer coordinates, given as front-end values, specifying the 
upper bounds of the clipping range for the x and y coordinates. 

coord length An unsigned integer specifying the length of the coordinates used 
for x start Jield, y_startJield, xendJield, and y_end Jield. 


DESCRIPTION 

CMSR_s_clip_lines clips the line coordinates in the fields x_start Jield, y_start_ 
field, x_end Jield, and y_end Jield against the clipping range defined by x jnin, yjnin, 
xjnax, and, yjnax. These fields may then be used in a call to CMSR_s_draw_lines 
to draw the clipped set of lines into a CM image buffer. 

CMSR_s_clip_lines modifies the line coordinate fields as follows: 

■ If a line falls completely outside the clipping range, this routine clears the test 
flag of the virtual processor containing that line’s coordinates. 

■ If only a portion of a line falls within the clipping range, this routine sets the 
virtual processors’ test flag and clips the out-of-range coordinates to the edge 
of the clipping box. To clip a line, the routine interpolates new endpoints for 
the line segment and overwrites the fields xjstartJield, y_startJield, x_end_ 
field, and y end Jield for that line. 

■ If the line falls completely within the clipping range, the routine sets the virtual 
processors’ test flag and leaves the line coordinates unchanged. 

NOTE: Before using these clipped fields as source fields for CMSR_s_draw_line, you 
must use the Paris instruction CM_logand_context_with_test to load the context 
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flags of the coordinate fields’ VP set with the modified test flag values. (See the Paris 
Reference Manual and Getting Started in C/Paris Programming, Chapter 4, for more 
information.) 


ERRORS 

With CM safety turned on, an error is signaled if xjnin is not less than or equal to 
x_max and yjnin is not less than or equal to y max. 


SEE ALSO 

CMSR_f_clip_lines 
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CMSR_s_draw_sphere 

Draws a set of spheres into the CM image buffer field. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr. h> 


void 

CMSR_s__dr aw_jsphe re 

( imagejbufferJield, xyzvectorJield, minjolorJield, 
maxjolorJeld,sphereJnfo Jield, radius Jield\ ncomponents, 
coord Jen, color Jen, sphereJnfoJen, radius Jen, anti alias) ; 


CMSR_field_id_t 
CMSR_fieldJLd_t 
CMSR_fieldJLd_t 
CMSR_field_id_t 
unsigned int 
unsigned int 
unsigned int 
CMSR anti alias t 


image_buffer Jield, xyzjyectorJield; 
minjolorJield [ncomponents] ; 
maxjcolorJeld [ncomponents]', 
sphere Jnfo Jeld, radius Jeld; 
ncomponents, coord Jen; 
color Jen [ncomponents ]; 
sphere Jnfo Jen, radius Jen ; 
anti alias; 


Fortran Syntax 

INCLUDE'/usr/include/cm/cmsr-draw-fort.h 
SUBROUTINE CMSRJSJDRAWJSPHERE 

& (imageJuffer Jeld, xyzjvector Jeld, minjcolor Jeld, maxjcolor Jeld, 

& sphere JnfoJeld, radiusJeld, ncomponents, coord Jen, 

& color Jen, sphere Jnfo Jen, radius Jen, antijilias) ; 

INTEGER image Jujfer Jeld, xyzjyector Jeld 

INTEGER minjcolorJeld(ncomponents), maxjcolorJeld(ncomponents ) 
INTEGER sphere JnfoJeld, radiusJeld, ncomponents, coord Jen 
INTEGER colorJen(ncomponents), sphere Jnfo Jen, radius Jen, antijilias 


Lisp Syntax 

This routine is not available from Lisp. 
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ARGUMENTS 

imagejbufferJield 


xyz_vectorJield 


mincolorJield 


max color Jield 


sphere info Jield 


radiusJield 
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A Paris field identifier. The image buffer is the field into which 
the spheres are drawn. The image Juffer field must be at least 
{color Jen * ncomponents) + sphere Jnfo Jen bits. 

A Paris field identifier specifying the field containing the 
coordinates, in screen coordinate space, of the center point of each 
sphere. 

The coordinates are signed integer values of coord Jen length. 
The length of the entire field must be 3 * coord len bits. The 
vector field is organized so that x occupies the least significant 
coord len bits, y occupies the next coord len bits, and z the most 
significant coord Jen bits. 

An ncomponent array of Paris field identifiers specifying the 
fields containing the minimum color for each color component. 
The min_color field is unsigned. 

The minimum color is the lowest color map entry to be used to 
draw the sphere. Spheres are shaded from maxcolor at the center 
to min color at the edge. 

An ncomponent array of Paris field identifiers specifying the field 
containing the maximum color for each sphere. The max color 
field is unsigned. 

The maximum color is the highest color map entry to be used to 
draw the sphere. Spheres are shaded from max color at the center 
to min color at the edge, or if min color is 0, to black. 

A Paris field identifier specifying an optional sphere information 
field. This field can be defined and used by the programmer in any 
way that is useful to the application. The sphere information is 
placed in the most significant sphere info Jen bits of image_ 
buffer. 

The sphere info placed in the imagejbuffer is applied to the 
sphere closest to each pixel. 

A Paris field identifier. The radius of each sphere to be drawn. 
This field must be radius Jen bits long. 

The radii of the spheres must all be the same, or must decrease 
with increasing z. 
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ncomponents An unsigned integer specifying the number of color components 
that will be used to specify color for all spheres. The number of 
color components must be at least 1. 

coord Jen The length, in bits, of a single coordinate value as specified in 

xyzjyector. 

color Jen An ncomponent array giving the length, in bits, of each color 

component in the image Juffer field. For example, for RGB true 
color, ncomponents is 3 and color Jen for each component is 8. 

sphere Jnfo Jen The length, in bits of the optional sphere information field. 

radius len The length, in bits, of the value specified in radius. 

anti alias An enumerated variable indicating the method of anti-aliasing to 

be applied when drawing the spheres. Valid values are: 

■ CMSR_no_anti_alias 

No anti-aliasing is performed. 

■ CMSR_edge_anti_alias 

Performs anti-aliasing at the edges between spheres and 
the background, but leaves jagged edges where spheres 
interpenetrate. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_s_draw_sphere draws a 
sphere into the image Juffer field in CM memory. The fields xyz_yector, mincolor, 
max color, sphere info, and radius must all be in the current VP set when CMSR_s_ 
draw_sphere is called. 

Each sphere is centered at the screen coordinates specified by the x and y components 
of the xyzjyector field and is drawn with a radius of radius. If the center of the sphere is 
outside the boundaries of the image, the entire sphere is not drawn; otherwise, portions 
of the sphere outside the image boundaries are clipped. Where spheres intersect, the 
sphere with smaller z coordinates (nearer the viewer) overwrite spheres with larger z 
values. 
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NOTE 

CMSR_s_draw_sphere calculates hidden surface removal for 
the set of spheres before drawing them to the image buffer. This 
routine does not write the z coordinate to a user accessible z-buffer 
field as do the 3D point drawing routines, CMSR_f_draw_ 
point_3d, CMSR_f e_f_draw_point_3d, and CMSR_s_draw_ 
point_3d. 


The color components are written to the least significant bits of the imagebujfer field, 
followed by the sphere info. When the image buffer is written to a display, the low bits 
of the field are interpreted as a color value to the depth (or bits per pixel) of the display 
and the high-order bits are left unchanged. The sphere info portion of the field may be 
used by the application as required. 

The spheres are shaded as though a light source were placed at negative infinity along 
the z axis. Shading is based on the range of colors in the display color map from 
max color to mincolor. The color specified by max color is drawn at the center of the 
sphere and color values are then interpolated over the range of colors to min color at 
the edge of the sphere. 

If the antialias argument is CMSR_edge_anti_alias , anti-aliasing is performed to 
smooth the sphere edges. However, two restrictions apply to anti-aliasing: 

■ No anti-aliasing is performed where the edge of a sphere intersects with 
another sphere. 

■ The color map from min_color to max_color for each color component must 
be a single range that increases linearly. That is, if ncomponents is 1, the color 
map must be set up, like a grayscale map, as a single ramp from black to some 
maximum color. If ncomponents = 3, each component must contain a single 
linear ramp. 
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CMSR_draw_image 

Transfers a subarray of a CM source field into the CM image buffer field. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 


void 

CMSR_draw_image 

(imagejbuffer Jield, sourceJield, source Jength, xjoffset, yjoffset, 
xjstart, yjstart, xjimit, yjimit, combiner); 


CMjf ield_id_t 
unsigned int 
int 
int 

CMSR combiner 


image buffer Jield, sourceJield; 

sourceJength ; 

xjoffset, yjoffset; 

xjstart, yjstart, xjimit, yjimit; 

combiner; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort. h' 

SUBROUTINE CMSR_JDRAW__IMAGE 

& (imageJufferJield, sourceJield\ source Jength, xjoffset , yjoffset, 

& xjstart, yjstart, xjimit, yjimit, combiner) 

INTEGER image JufferJield, source Jield, source Jength 
INTEGER xjoffset, yjoffset x_start, yjstart, xjimit,yjimit 
INTEGER combiner 


Lisp Syntax 

CMSR: draw-image (image-bufferJield source Jield source-length 
x-offset y-offset x—start y-start x-limit y-limit 

&key (combiner ‘.default)) 
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ARGUMENTS 

image bufferJield A Paris field containing unsigned integers. The sourceJield is 
copied into this field beginning at the location specified by 
x offset and y_offset. The image JufferJield must be in a 
two-dimensional VP set, and may or may not be in the same VP set 
as the source Jield. It need not be in the current VP set. 

source Jield A Paris field containing unsigned integers. This field, within the 

subarray specified by x_start, y_start, xjimit, and yjimit, is 
copied into image buffer Jield. The source Jield must be in a 
two-dimensional VP set, and must also be in the current VP set. 

source length An integer specifying the length of the data values in the 
source Jield field. The value of source length must be less than, 
or equal to, the length of the image buffer field. 

x offset, y_offset Front-end integer values, specifying the location in the image 
buffer field at which to begin loading the values from the 
sourceJeld. 

x_start,y_start, x limit,yjimit 

Front-end integer values, defining the location of a rectangle in 
source Jeld from which values are taken to be loaded into 
image buffer Jeld. The values moved include the value at the 
start location, but exclude the value at the limit location. 

combiner A symbol defining the method used to combine the array values 

being transferred from the source array with the values already in 
the image buffer field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR__de fault 

CMSR_default 

:DEFAULT 

CMSR_overwr i te 

CMSR__o ve rwr i t e 

:OVERWRITE 

CMSR_logior 

CMSR_logior 

:LOGIOR 

CMSR_logand 

CMSR^JLogand 

:LOGAND 

CMSR__logxor 

CMSR^logxor 

:LOGXOR 

CMSKjijSkdd 

CMSR__u__add 

:U—ADD 

CMSR__s__add 

CMSR_s_add 

:S-ADD 

CMSR_u_min 

CMSR__u_min 

: U—MIN 

CMSR_sjmin 

CMSR_s_min 

: S—MIN 

CMSR_j2_max 

CMSR_ji_max 

:U—MAX 

CMSR_sjmax 

CMSR_s_max 

:S—MAX 
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DESCRIPTION 

CMSR_draw_image transfers the values in the Paris field source Jield, within the sub¬ 
array specified by x_start, y_start, xjimit, and yjimit into image JufferJield. The 
subarray will be loaded into image Juffer Jeld beginning at the location specified by 
xjyffset and y_offset. 

Both sourceJield and image JufferJield must be associated with VP sets with 
two-dimensional geometries. 

The source Jeld coordinates ( x_start, y_start) and (xjimit, yjimit) define the sub¬ 
array to be moved to the image buffer field. The first element, at the virtual processor 
location (xstart, y start), is moved to the location in the image buffer field specified 
by ( x_offset, yjoffset). The last source element moved is at location (xjimit - 1 , 
yjimit -1). The width of the the rectangle is xjimit - x start, and the height is yjimit 
-y_start. 


x start must be less than xjimit, and y start must be less than yjimit. 

The value written into each location in the image buffer is a combination of the value of 
source Jeld, the previous value at that location, and the value of any other lines writ¬ 
ing to the same location. The method used to combine these values is controlled by the 
combiner parameter. 


ERRORS 

With CM safety mode on, an error is signaled if you call CMSR_draw_image with 

■ start coordinate indices greater than, or equal to, the limit coordinates 

■ start or limit coordinate indices that are out of the bounds of the source field 

■ offset coordinate indices that are out of the bounds of the image buffer field 

■ a coordinate index sum ( offset + (limit - start)), which is out of the bounds of 
the image buffer field 

■ a sourceJeld or image JufferJeld that does not have a two-dimensional VP 
set geometry 

■ a source length that is longer than the length of the image JufferJeld or 
sourceJeld 

■ source field not in the current VP set 
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CMSR_fe_draw_rectangle 

Fills a rectangle in a CM image buffer field with a specified color. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_f e__dr aw__r e c tangle 

{image buffer Jield\ x, y, width, height, color\ depth) 


CM_field_id_t 

imageJufferJield; 

int 

x; 

int 

>>; 

int 

width; 

int 

height; 

int 

color; 

unsigned int 

depth; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_FE_DRAW__RECTANGLE 

& {imageJbuffer Jield, x, y, width, height, co/or, depth) 

INTEGER field; 

INTEGER x; 

INTEGER 
INTEGER width; 

INTEGER height; 

INTEGER color; 

INTEGER ; 


Lisp Syntax 

CMSR: f e-draw-rectangle 

(imageJoufferJield, x, y, width, height, color, depth) 
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ARGUMENTS 

imageJufiferJield A Paris field identifier. The specified rectangle is drawn io to ^s 
field. The image_bufferJield must be in a two-dimensio° a ^ VP 
set. It need not be in the current VP set. 

jc, y The position in the image buffer field at which to begin drawing 

the rectangle. The position is measured in pixels from th e u PP er 
left comer, x is the horizontal distance to the right, y is the vertical 
distance down. 

width , height The dimensions in pixels of the rectangle to be drawn, width is the 

horizontal distance of the rectangle from (jc, y). height is the 
vertical distance of the rectangle from (x, y). 

color An integer specifying the color value to be written into the image 

buffer field. 

depth The length, in bits, of the image buffer field. 


DESCRIPTION 

CMSR_f e_draw_rectangle draws a filled rectangle of the specified color into the 
image buffer field. The x and y arguments define the location in the image buffer at 
which to begin drawing the rectangle, and width and height specify the number of 
pixels in each dimension of the image. The rectangle fills the image buffer from (x,y) 
at the upper left comer to ((jc + width), (y + height)) at the lower right. 


SEE ALSO 

CMSR_fe_display_rectangle 
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CMS R_wri te_a r ray_to_f i e I d 

Writes an image packed into a front-end array to a CM image buffer field. 


SYNTAX 
C Syntax 

#include <cm/display.h> 
void 

CMSR_write__array__to__f ield 

( field, array, array width, arrayheight, array element size) ; 

CM_field__id_t field ; 

char * array; 

unsigned int array width, array height ; 

unsigned int array element size; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-draw-fort. h' 


& 


SUBROUTINE CMSR__WRITE_ARRAY_TO_JTIELD 

(field, array, array width, array height, array element size) 


INTEGER field 
CHAR* (*) array 
INTEGER array_width 
INTEGER arrayjieight 
INTEGER array_element_size 


Lisp Syntax 

CMSR:write-array-to-field 

(field, array, ^optional [array-element-size nil)) 


ARGUMENTS 

field The destination field. This field must be 2D. 
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array 

array_width 


arrayheigh 


A 2D array on the front-end computer to be copied to the field. 

The number of image elements, in array_element_size units, 
along the faster varying dimension of the front-end array. For 
Fortran this is the first index; for C this is the second index. This 
is the axis that is mapped to axis 0 of the field. 

Because CMSR_write_array_to_field does packed-bit 
transfers, the width of the array must be byte-aligned, that is, 
(arrayjwidth * array element size) % 8 = 0 

For Lisp, the array dimensions can be determined and must not be 
specified. 

The number of image elements along the slower varying 
dimension of the front-end array. For Fortran this is the second 
index; for C this is the first index. This axis is mapped to axis 1 
in the field. 

For Lisp, the array dimensions can be determined and must not be 
specified. 


array element size The length, in bits, of the image array elements packed into the 
front-end array, array. Usually this is the depth of the image to be 
displayed. 

This must be a power of two between 1 and 128. In Lisp, this 
defaults to the actual size of an array element. 


DESCRIPTION 

CMSR_write_array_to_field copies an image array packed into array on the 
front-end computer to field in CM memory. The front-end array must be a 2D array but 
can be any front-end data type. 

The three parameters array_width, arrayJieight, and array elementsize define the 
image array packed into the front-end array array. The array_element_size argument 
specifies the length in bits of each pixel value in the image array. The arguments 
arraywidth and array Jieight are the total number of image elements (pixels) in each 
dimension of the image array. 

Beginning at the first element of the array, an arrayjvidth by array Jieight rectangle of 
array_element_size units is copied into the CM field, overwriting any pixel values that 
are already stored there. The array is transferred so that the fastest varying front-end 
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dimension maps to axis 0 on the CM. Therefore, the CM field should have axis 0 of at 
least length array jvidth and axis 1 of length array height to hold all of the array. 

If the arrayjvidth or array height is larger than the field, the image array elements 
beyond the field boundaries to the right and bottom are clipped. 

If the array jvidth or array height is smaller than the field dimensions, the portion of 
the field beyond the array width and height is left unchanged. 

Note that array jvidth, arrayJieight, and array element size refer to the image array 
to be transferred, not to the front-end array in which the image is stored. For example, a 
128 by 128 1-bit image could be packed into a 16 by 128 front-end char or charac¬ 
ter array, 8 image array elements to a front-end array element. When CMSR_ 
write_array_to_field writes this image with an array element size of 1 to the 
field, each byte of the front-end array source, fills the 1-bit image field in 8 CM proces¬ 
sors. If the image array element size were 8, each byte of the front-end array would go 
to a single CM processor. 

To take one more example, 128 x 128 image that is 32 bits deep might be stored in a 
512 x 128 front-end character array; each pixel’s data packed into 4 front-end array 
elements. If this array was passed to CMSR_write_array_to_field_l with an 
array element size of 32 each 4 bytes of the front-end array would be stored in the 
field of a single CM processor. 

CMSR_write_array_to_f ield uses the byte ordering of the front-end computer. So 
if the front-end byte ordering is MSB-first, the most significant byte and bit of the array 
elements go to the lowest processor address in CM memory. 


SEE ALSO 

CMSR_write_array_to_fie1 d_l 
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CMSR_write_array_to_field_1 

Writes a specified subarray of an image packed into a front-end array to a CM image buffer 
field. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr-draw.h> 


void 

CMSRjwxi te__ar r ay__to_f ie ld_l 

{field, array, array width, array height, array element size, 
xoffset, yoffset, xstart, ystart, width, height, 
xjyaries Jastest_p, combiner) 


CMj£ield__id__t 

void 

unsigned int 

unsigned int 

int 

int 

int 

int 

CMSR combiner 


field; 

* array; 

array_width, array height; 
array ^element_size; 
xoffset, yoffset ; 
xstart, ystart; 
width, height; 
xparies Jastest_p; 
t combiner; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 


SUBROUTINE CMSR_WRITE_ARRAY_TO_FIELD__l 

& {field, array, arrayjwidth, array Jieight, array^element size, 
& xoffset, yoffset, xstart, ystart, width, height, 

& x_variesJastest_p, combiner) 


INTEGER field 
CHAR* (*) array 

INTEGER arrayjwidth, array Jieight 
INTEGER array_element-Size 
INTEGER xoffset, yoffset 
INTEGER xstart, ystart 
INTEGER width, height 
INTEGER x-VariesJastest_p 
INTEGER combiner 


74 


Version 2.0, November 1991 



Chapter 2. Drawing Routines 


CMS R_write_array_to__field_1 


Lisp Syntax 

CMSR:write-array-to-fieldJL {field array &key array-element-size 

xojfset yoffset xstart ystart width height 
(x-varies-fastest-p t) combiner) 


ARGUMENTS 

field 

array 


array_width 


arrayheight 


The destination field. This field must be 2D. 

An array on the front-end computer containing the image data to 
be copied to the field. 

The number of image elements, in array element size units, 
along the faster varying dimension of the front-end array. For 
Fortran this is the first index; for C this is the second index. If 
x variesfastest_p is true, this is the axis that is mapped to axis 0 
of the field. 

Because CMSR_write_array_to_field does packed-bit 
transfers, the width of the array must be byte-aligned, that is, 
{array width * array element size) % 8 = 0 

For Lisp, the array dimensions can be determined and must not be 
specified. 


The number of image elements, in array element size units, 
along the slower varying dimension of the front-end array. For 
Fortran this is the second index; for C this is the first index. If 
x_yaries Jastest_p is true, this axis is mapped to axis 1 in the field. 

For Lisp, the array dimensions can be determined and must not be 
specified. 


array element size The length, in bits, of the image array elements packed into the 
front-end array, array. Usually this is the depth of the image to be 
displayed. 

This must be a power of two between 1 and 128. In Lisp, this 
defaults to the actual size of an array element. 

xojfset, yoffset The location in array at which to begin copying data. The xoffset 
is the number of elements along the width (i.e., the faster varying) 
dimension of the array in units of array_element_size. The yoffset 
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xstart, ystart 

width 


height 


combiner 


x_varies _ fastest_p 


field 1 


is the number of elements along the height (i.e., the slower 
varying) dimension. In Lisp, this defaults to (0,0). 

xoffset and yoffset must be non-negative. 

The location in field at which to begin writing the image array. 
xstart is measured along axis 0; ystart is measured along axis 1. 

The number of image array elements, in arrayelementsize units, 
to be transferred along the horizontal (i.e., the faster varying) 
dimension of the array. In Lisp, this defaults to array_width. 

The number of image array elements to be transferred along the 
vertical (i.e., the slower varying) dimension of the array. In Lisp, 
this defaults to array height. 

A symbol defining the method used to combine the color values 
being written from the array into the field with the values already 
in the field. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_default 

CMSR_default 

:DEFAULT 

CMSR__ove rwr i te 

CMSR__ove rwr i te 

.•OVERWRITE 

CMSR_logior 

CMSR_ logior 

:LOGIOR 

CMSRJLogand 

CMSR_logand 

:LOGAND 

CMSR_JLogxor 

CMSR__logxor 

:LOGXOR 

CMSRjajSidd 

CMSR_u_add 

:U-ADD 

CMSR - s - add 

CMSR_s_add 

:S—ADD 

CMSR_u_min 

CMSR^ujnoin 

: U—MIN 

CMSR__s_min 

CMSR__s_min 

: S—MIN 

CMSR_u_max 

CMSR_jijmax 

:U—MAX 

CMSR_sjmax 

CMSR_sjmax 

: S—MAX 


If x_varies Jastest_p is tme (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp), the front-end array is mapped directly to the field, 
aligning the faster-varying axis of the array to axis 0 of the field. 
This produces the correct results for Fortran arrays and for C 
arrays that are referenced [y][x]. 

If x varies _ fastest_p is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), the front-end array is transposed as it is transferred to the 
field; the faster-varying axis of the array is mapped to axis 1 of the 
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field. This produces correct results for C arrays that are referenced 

MM- 


DESCRIPTION 

CMSR_write_array_to_f ield_l copies a specified subarray of the image packed 
into array on the front-end computer to field in CM memory. The front-end array must 
be a 2D array, but it can be any front-end data type that provides a length in bits that is a 
power of two between 1 and 128. 

The three parameters, arrayjwidth, array height, and array element size define the 
image array packed into the front-end array array. The array element size argument 
specifies the length in bits of each pixel value in the image array. This is the size of each 
data elements that will be transferred to a CM processor. The arguments array_width 
and array height are the total number of image elements (pixels) in each dimension of 
the image array. 

Note that array width, array Jieight, and array_element_size refer to the image array 
to be transferred, not to the front-end array in which the image is stored. For example, a 
128 by 128 1-bit image could be packed into a 16 by 128 front-end char or CHARAC¬ 
TER array, 8 image array elements to a front-end array element. When CMSR_ 
wri te_array_to_f ield_l , with an array element size of 1, writes this image to 
the field, each byte of the front-end array source fills the 1-bit image field in 8 CM 
processors. If the image array_element_size were 8, each byte of the front-end array 
would go to a single CM processor. 

To take one more example, 128 x 128 image that is 32 bits deep might be stored in a 
512 x 128 front-end character array; each pixel’s data packed into 4 front-end array 
elements. If this array was passed to CMSR_write_array_to_field_l with an 
array element_size of 32, each 4 bytes of the front-end array would be stored in the 
field of a single CM processor. 

The arguments xoffset, yoffset, width, and height define the subarray within the image 
array that is to be transferred, xoffset and yoffset define the location in the image array, 
in array element size units, at which the transfer should begin, width and height are 
the number of image array elements to be transferred in each direction. So, the portion 
of the image array to be transferred is the subarray from ( xoffset, yoffset) at the upper 
left comer, to {(xoffset + width), (yoffset + height )) at the lower right comer. 

Each image element of the subarray is transferred to the corresponding location in the 
image buffer field beginning at the point defined by (xstart,ystart). Each array element 
value is combined with the pixel value at the corresponding field location according to 
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CMS R_wr ite_a rray_t o_fi e I d_1 


the value of combiner. The default value is to overwrite. If the array_ element size is 
smaller than the depth of the field, an error is signaled. If the array_ element size is 
larger than the depth of the field, only the lower-order bits of the array element, up to 
the field’s depth, are used. 

If the width or height of the image to be transferred is larger than the image buffer field 
dimensions, the portion of the array beyond the field boundaries to the right and bottom 
is clipped. If the width or height of the image to be transferred is smaller than the field, 
the portion of the field beyond the array width and height is left unchanged. 

CMSR_write_array_to_f ield_l uses the byte ordering of the front-end computer. 
So if the front-end byte ordering is MSB-first, the most significant byte and bit of the 
array elements go to the lowest processor address in CM memory. 


SEE ALSO 

CMSR_write_array_to_field 
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CMS R_read_array_f rom_fi eld 


CMS R_rea d_a r r ay_f ro m_f i e I d 

Packs an image array from a CM field into a front-end array. 


SYNTAX 
C Syntax 

#include <cm/cmsr-draw. h> 
void 

CMSR_read__ar r ay_f r om_f i e Id 

{field, array, array width, array height, array element size ); 

CM__f i e 1 d_i d_t field ; 

CMSR_generic_pointer__t array ; 

unsigned int array_width, array height ; 

unsigned int array element_size; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-draw-fort.h' 

SUBROUTINE CMSR_READ_ARRAY_FROM__FIELD 

& {field, array, array width, arrayJieight, array_element_size) 

INTEGER field 
CHAR* (*) array 
INTEGER array width 
INTEGER array Jieight 
INTEGER array_element_size 

Lisp Syntax 

CMSR:write-array-to-field 

{field, array, fioptional array-element-size) 


ARGUMENTS 

field The source field. This field must be 2D. 
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array 


A 2D front-end array into which the data from the field is to be 
read. 


array width The number of elements, in array_element_size units, to be stored 

along the faster varying dimension of the front-end array. For 
Fortran this is the first index; for C this is the second index. Axis 
0 of the field is mapped to this dimension of the array. 

Because CMSR_read_array_from_field does packed-bit 
transfers, the array width must be byte-aligned, that is, 

(array_width * array_element_size) % 8 = 0 

array height The number of elements to be stored along the slower varying 
dimension of the front-end array. For Fortran this is the second 
index; for C this is the first index. Axis 1 of the field is mapped 
to this axis. 

For Lisp, the array dimensions can be determined and must not be 
specified. 


array_element_size The length, in bits, of field. This will also be the size of the image 
array elements stored in the front-end array array. This must be a 
power of two between 1 and 128. In Lisp, this defaults to the 
actual size of an array element. 


DESCRIPTION 

CMSR_read_array_f rom_f ield reads image values from field and packs them into 
array on the front-end computer. 

The front-end array must be a 2D array but can be any front-end data type. If the array 
is not large enough to hold the entire field, the portions of the field image on the right 
and bottom (+x, +y) beyond the array dimensions are clipped. 

The three parameters array width, array height, and array element size define the 
image array in field to be packed into the front-end array array. The array_element_ 
size argument specifies the depth of the field, array jvidth is the length of axis 0 and 
array_height is the length of axis 1. The array is transferred so that axis 0 of field maps 
to the fastest varying dimension of the front-end array. 

Note that array jvidth, array height, and array_element size refer to the image array 
to be transferred, not to the front-end array in which the image is stored. For example, a 
128 by 128 1-bit image could be packed into a 16 by 128 front-end char or CHARAC¬ 
TER array, 8 image array elements to a front-end array element. When CMSR_ 
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CMSR_read_array_from_field 


read_array_f rom_f ield writes this image to the front-end array, the image field in 
8 CM processors fills a byte of the front-end array. If array_element_size is 8, each CM 
processor fills a byte of the front-end array elements, and if array element size is 32, 
each CM processor fills a word of the front-end array elements. 

CMSR_read_array_from_f ield uses the byte ordering of the front-end computer. 
So if the front-end byte ordering is MSB-first, the most significant byte and bit are 
taken from the lowest processor address in CM memory. 


SEE ALSO 

CMSR_read_array_from_field_l 
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CMSR_read_array_from_field_1 


CMS R_rea d_a rray_f ro m_f i e I d_1 

Packs a specified subarray of an image in a CM image buffer field into a subarray of a 
front-end array. 


SYNTAX 
C Syntax 

♦include <cm/cmsr-draw. h> 


void 

CMSR_read_array_from_field_l 

{field, array, array width, array height, array elementsize, 
xojfset, yojfset, xstart, ystart, width, height, 
xjyariesJastestjp, combiner) 


CMJfieldJLd_t 

CMSR_generic_pointer_t 

unsigned int 

unsigned int 

int 

int 

unsigned int 
int 

CMSR combiner t 


field; 

array; 

array width, array height; 

array element_size; 

xoffset, yoffset ; 

xstart, ystart; 

width, height; 

xjyariesJastest_p; 

combiner; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-draw-fort. h' 


SUBROUTINE CMSR_READ___ARRAY_FROM_FIELD__l 

& {field, array, arrayjwidth, array Jieight, array_element_size, 

& xoffset, yoffset, xstart, ystart, width, height, 

& x_yaries Jastestjp, combiner) 


INTEGER 

CHAR* (*) 

INTEGER 

INTEGER 

INTEGER 

INTEGER 

INTEGER 

INTEGER 

INTEGER 


field 

array 

array_width, array Jieight 

array_elem en t_size 

xoffset, yoffset 

xstart, ystart 

width, height 

x_yaries Jastestjp 

combiner 


82 


Version 2.0, November 1991 




Chapter 2. Drawing Routines 


CMSR_read_array_from_field_1 


Lisp Syntax 

CMSR: read-array-from-f ield_l (field array &key array-element-size 

xojfset yoffset xstart ystart width height 
(x-varies-fastest-p t) combiner) 

ARGUMENTS 

field The source field. This field must be 2D. 

array A 2D front-end array into which the data from the field is to be 

read. 

array width The number of elements, in array element size units, to be stored 

along the faster varying dimension of the front-end array. For 
Fortran this is the first index; for C this is the second index. 

Because CMSR_read_array_from_field does packed-bit 
transfers, the array width must be byte-aligned, that is, 

{array width * array element size) % 8 = 0 

array height The number of elements, in array element size units, to be stored 
along the slower varying dimension of the front-end array. For 
Fortran this is the second index; for C this is the first index. 

For Lisp, the array dimensions can be determined and must not be 
specified. 

array element_size The length, in bits, of field. This will also be the size of the image 
array elements stored into the front-end array array. This must be 
a power of two between 1 and 128. In Lisp, this defaults to the 
actual size of an array element. 

xojfset, yoffset The offset into the array at which to begin writing the data from 
the field. The xoffset is the number of elements along the width 
(i.e., the faster varying) dimension of the array in units of 
array_element_size. The yoffset is the number of elements along 
the height (i.e., the slower varying) dimension. In Lisp, this 
defaults to (0,0). 

xoffset and yoffset must be non-negative. 

xstart, ystart The location in field at which to begin reading the image. x_start 
is measured in grid coordinates along axis 0 ,y_start along axis 1. 
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width 


height 


xjvariesJastest_p 


combiner 


The number of image array elements, in arrayjelementsize units, 
to be transferred along the horizontal (i.e., the faster varying) 
dimension of the array. In Lisp, this defaults to array width. 

The number of image array elements to be transferred along the 
vertical (i.e., the slower varying) dimension of the array. In Lisp, 
this defaults to array height. 

Indicates whether the first or second array index varies fastest in 
array. 

If x_variesfastest_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp), the axis 0 of the field is mapped directly to the 
faster-varying axis of the array. This produces the correct results 
for Fortran arrays and for C arrays that are referenced [y][x]. 

If x varies Jastest_p is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), the image data is transposed as it is transferred from the 
field into the array so that axis 1 of the field is mapped to the 
faster-varying axis of the array. This produces correct results for 
C arrays that are referenced [x][y]. 

x_variesfastest_p should be true for Fortran arrays or for C 
arrays that are referenced [y][x]. For C arrays referenced [x]\y], 
xjyariesJastest_p should be false. 

A symbol defining the method used to combine the color values 
being written from the field into the array with the values already 
in the array. Valid values are listed in the table below. 


C Values 

Fortran 

Values 

Lisp 

Keywords 

CMSR_default 

CMSR_default 

:DEFAULT 

CMS R__o ve rwr i te 

CMS R__o ve rwr i te 

.•OVERWRITE 

CMSR_logior 

CMSR__logior 

:L06I0R 

CMSRJLogand 

CMSR^logand 

:LOGAND 

CMSR_logxor 

CMSR__logxor 

:LOGXOR 

OMSRjujadd 

CMSR_u__add 

:U-ADD 

CMSR_s_add 

CMSR_s___add 

:S-ADD 

CMSR_u_min 

CMSR__u__min 

: U—MIN 

CMSR_s__min 

CMSR_sjmin 

: S—MIN 

CMSR_u_max 

CMSR_u__max 

: U-MAX 

CMSR__s__max 

CMSR__s__max 

:S-MAX 
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DESCRIPTION 

CMSR_read_array_f rom_f ield_l reads a subarray or the image in field and packs 
it into array on the front-end computer. The front-end array must be a 2D array but can 
be any front-end data type that provides an appropriate number of bits for the depth of 
the field. 

The three parameters array width, array height, and array element size define the 
image array in the field from which the subarray is to be read. The array element size 
argument specifies the depth of the field, array_width is the length of axis 0 and 
array Jieight is the length of axis 1. The array is transferred so that axis 0 of field maps 
to the fastest varying dimension of the front-end array. 

Note that arraywidth, array Jieight, and array element size refer to the image array 
to be transferred, not to the front-end array in which the image is stored. For example, a 
128 by 128 1-bit image could be packed into a 16 x 16 front-end char or CHARACTER 
array, 8 image array elements to a front-end array element. When CMSR_read_ 
array_f rom_f ield writes this image to the front-end array, the image field in 8 CM 
processors fills a byte of the front-end array. If array_element_size is 8, each CM pro¬ 
cessor fills a byte of the front-end array elements, and if array element size is 32, each 
CM processor fills a word of the front-end array elements. 

The arguments xoffset and yoffset specify the location in the font-end array at which to 
begin reading in the data from the field. The subarray of the field to be read is defined 
by the arguments xstart, ystart, width and height. The portion of the field to be read is 
from {xstart, ystart) at the upper left comer, to {{xstart + width), {ystart + height) at the 
lower right. If the array is not large enough to hold the entire field subarray, the por¬ 
tions of the field on the right and bottom (+x, +y) beyond the array dimensions are 
clipped. 

CMSR_read_array_from_field_l uses the byte ordering of the front-end com¬ 
puter. So if the front-end byte ordering is MSB-first, the most significant byte and bit 
are taken from the lowest processor address in CM memory. 


SEE ALSO 

CMSR_read_array_f rom_field 
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Math Routines 


This chapter documents the *Render Math routines. These routines provide utilities for 
performing common graphics math operations on vectors and matrices in front-end arrays 
or Connection Machine (CM) fields. 

In addition, a set of routines is included for converting between the color spaces RGB, 
CMY, YIQ , HSV, and HSL. 

The next section provides an overview of these routines. Following sections provide 
detailed descriptions of the individual routines. 


3.1 Overview 

In many applications it is necessary to manipulate the image’s coordinate data for display. 
You must often scale, rotate, and translate objects in the image to position them properly 
in the display. 

The standard method for applying geometric operations to the image coordinates is through 
transformation matrices. In this method the point coordinates are represented as vectors 
(e.g.,[ x, y, z]) and a matrix is composed representing the transformation to be performed 
on the image. By applying the matrix to the set of point vectors, using the conventions of 
matrix algebra, we can generate a new set of coordinates defining the transformed position 
of the object in the display space. 

*Render provides functions to allocate vector and matrix structures in either CM memory 
or on the front-end computer, and to perform the basic matrix operations. The routines that 
operate on front-end vectors and matrices operate on a single instance of these structures 
allocated as front-end arrays. The CM routines operate on a field of vectors or matrices in 
parallel. 
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If you would like more information on the use of matrix method, please see any basic text 
on computer graphics. Two particularly useful discussions are found in 

■ David F. Rogers, Mathematical Elements for Computer Graphics (New York: 
McGraw-Hill, 1990). 

■ James D. Foley, Andries van Dam, Steven K. Feiner, and John F. Hughes, Com¬ 
puter Graphics: Principles and Practice, 2d ed. (Reading, Mass.: Addison-Wesley, 
1990). 


3.1.1 Vectors 

Vectors in *Render are one-dimensional arrays of either two or three elements. 

On the front-end computer, each vector is an array of double-precision floating-point val¬ 
ues. On the CM, each vector is a single field of (dimension)*(signifJen+exp_len+ 1) bits, 
where signifjen is the length of the significand, exp len is the length of the exponent, and 
the 1 is for a sign bit. Each element of the vector occupies a subfield of ( sig- 
nif_len+expJen+\) bits, and these subfields are arranged so that element 0 is in the least 
significant bits. 

In a position vector, representing the coordinates of a point, x occupies element 0, y occu¬ 
pies element 1, and z (if present) occupies element 2. 


3.1.2 Matrices 

Matrices in *Render are assumed to be square, homogeneous matrices. *Render supports 
matrices of dimension 2 or 3, for transforming two-dimensional or three-dimensional vec¬ 
tors. 

The fact that homogeneous coordinates are used implies that an extra row and column are 
added to the matrix: a matrix of dimension n contains (n+l)(n+l) elements. The additional 
row and column hold translation, perspective, and general scaling elements. The elements 
of a 3D transformation matrix are arranged as follows: 

column = 0123 


Where 


■ RS = rotation, reflection, skew, and scaling elements 


88 


Version 2.0, November 1991 



Chapter 3. Math Routines 


■ P = perspective elements 

■ T = translation elements 

■ GS = global scale element 

On the front end, a matrix is an appropriately sized array of double-precision floating-point 
values. On tbe CM, a matrix is a field of (dimension + 1) * (dimension + \)(signiflen + 
exp len +1) bits, where signiflen is the length of the significand, exp len is the length of 
the exponent, and the 1 is for a sign bit. Each matrix element occupies one floating-point 
field of ( signifjen + exp Jen +1) bits. 


3.1.3 Transformation Conventions 

*Render uses the following conventions for transformations: 

■ Objects and operations are defined in a right-handed coordinate system. 

■ Screen space is right-handed, with the origin in the upper left comer of the screen: 
x increases to the left, y increases downwards, and z increases into the screen, away 
from the viewer. 

■ Rotations are clockwise about an axis as seen by an observer at the origin looking 
along the axis in the positive direction. 


3.1.4 Color Spaces 

*Render provides routines to convert between several widely used ways of representing 
color. Each way of representing color may be thought of as a color “space.” For example, 
the RGB space can be pictured as a cube with three orthogonal axes for red, green, and blue. 

Following this model, a specific color is a vector in the appropriate color space. For the 
color spaces that ’•‘Render currently supports, colors are 3-element vectors. Color vectors 
are organized as shown in the following chart: 


Color Space 

Element 0 

Element 1 

Element 2 

RGB 

red 

green 

blue 

CMY 

cyan 

magenta 

yellow 

YIQ 

Y(luminance) 

I(chromaticity) 

Q(chromaticity) 

HSV 

hue 

saturation 

value 

HSL 

hue 

saturation 

lightness 
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The supported color spaces are: 

■ RGB 

Additive color model using three primaries (red, green, and blue) in a Cartesian 
coordinate system. * Render uses floating-point values to represent the contribu¬ 
tions of each primary. A value of 0.0 indicates no contribution, and 1.0 indicates 
full contribution. The main diagonal of this RGB “color cube” represents gray lev¬ 
els, with equal amounts of each primary. (0,0,0) is black, and (1,1,1) is white. 

■ CMY 

Subtractive color model using three primaries (cyan, magenta, and yellow) that is 
useful for hardcopy devices. This model uses the same Cartesian coordinate sys¬ 
tem as RGB, except that (0,0,0) is white and (1,1,1) is black. 

■ YIQ 

A re-coding of RGB that is used in commercial color television broadcast. The Y 
component is the luminance for a color. This term can therefore be used to display 
a color image as a grayscale image. The I and Q components encode chromaticity. 

■ HSV 

This model uses hue, saturation, and value to encode colors. The geometry of this 
space is a truncated hexcone. Hue is an angle from 0 to 2*pi radians. Red is at 0.0, 
green is at 2*pi/3 radians, and blue is at 4*pi/3 radians. Complementary colors are 
pi radians apart. Saturation is a fraction from 0.0 to 1.0. Value is a number from 
0.0 to 1.0. When S is 0.0, H is irrelevant. When V is 0.0, H and S are irrelevant. 
(Also called HSB.) 

• HSL 

Hue, lightness, and saturation. HSV deformed into a double hexcone. The hue ori¬ 
gin at 0.0 radians is red. 

Note that the saturation in HSV is not the same as that in HSL. 
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3.2 Front-End Vector Routines 

This section documents the *Render routines that operate on vectors in front-end arrays. 
Vectors in ^Render are one-dimensional arrays of either two or three elements allocated as 
an array of double-precision floating-point values. 


The routines documented here are: 

CMSR_f e_v__ab s_J 2 d. 93 

CMSR_fe_v_abs_3d. 93 

CMSR_fe_v_abs_squared_2d. 95 

CMSR_fe_v_abs_squared_J3d. 95 

CMSR_fe_v_add_2d. 97 

CMS R_f e_v_a dd_3 d. 97 

CMSR__fe_jv_copy_2d . 99 

CMSR_fe_v__copy_J3d . 99 

CMSR_f e_v__co s_be tween__2 d. 101 

04SR_fe_v_cos_betweenJ3d. 101 

<MSR_fe_v_cross_product_3d . 103 

GMSR_fe_v_dot_j>roduct_2d. 105 

C^R_fe_vjiotjproduct_J3d. 105 

CMSR_fe_v__is__zero_2d. 107 

CMSR_fe_y_is_zero_3d. 107 

CMSR_fe_v_negate_2d. 109 

CMSR_f e__v_nega t e_3 d. 109 

CMSR^fe_y_no rmalize__2d . Ill 

CMSR^fe_v_normalize__3d . Ill 

CMSR_fe__vjperpendicular_2d . 113 

CMSR_fe_vjperpendicular_3d . 113 

CMSR__f e_v_pr in t__2 d. 115 

CMSR__fe_vj?rint_3d. 115 

CMSR fe v reflect 2d. 117 
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CMSR_fe_v_reflect_3d. 117 

Q^R_fe_v_scale_2d. 119 

C^R_fe_v_scale_3d. 119 

C^R_£e_v_subtract_2d .. 121 

QMSR_fe_vjsubtract_3d . 121 

C^R_fe_v_transform_2d . 123 

CMSR_fe_v_transfomJ3d . 123 

CMSR fe v transmit 3d . 126 
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CMSR_fe_vabs_2d 
CMSR fe v abs 3d 


CMS R_fe_v_a bs_2 d 
CMS R_fe_v_a bs_3 d 

Returns the length of the specified front-end vector. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double 

CMSR_f e_v_ab s_2 d ( srcvector ) 
double src_vector[ 2]; 

double 

CMSR_fe_v_abs_3d ( src vector) 
double src_yector [ 3 ] ; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR_FE_V_ABS_2D (src_vector) 
DOUBLE PRECISION srcjyector (2) 

DOUBLE PRECISION FUNCTION CMSR_FE_V_ABS_3D ( src vector) 
DOUBLE PRECISION srcvector (3) 

Lisp Syntax 

CMSR: fe-v-abs-2d (src-vector) 

CMSR:fe-v-abs-3d (src-vector) 


ARGUMENTS 

src_vector The vector for which the length is to be calculated. For CMSR_f e_ 

v_abs_2d src_vector is a 1 x 2 front-end array of double¬ 
precision values. For CMSR_fe_y_abs_3d it is a 1 x 3 array. 
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CMSR_fe_v_abs_2d 

CMSR_fe_v_abs_3d 


DESCRIPTION 

CMSR_fe_v_abs_2d and CMSR_fe_v_abs_3d return the length of the vector 
src vector. 


SEE ALSO 

CMSR_fe_v_abs_squared_2d 

CMSR_fe_v_aJbs_squared_3d 

CMSR_v_abs_2d 

CMSR_v_abs_3d 

CMSR_v_abs_squared_2d 

CMSR_v_abs_squared_3d 
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CMSR_fe_v_abs_squared_2d 

CMSR_fe_v_abs__squared_3d 


CMSR_fe_v_abs_squared_2d 

CMSR_fe_v_abs_squared_3d 

Returns the square of the length of a specified 2D (3D) front-end vector. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double 

CMSR_fe_v_abs_squared_2d ( srcvector) 
double src vector [ 2] ; 

double 

CMSR_fe_v_abs_squared_3d (src vector) 
double src vector [ 3] ; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR_FE_V_ABS_SQUARED_2D (srcvector) 
DOUBLE PRECISION src_vector( 2) 

DOUBLE PRECISION FUNCTION CMSR_FE_V_ABS_SQUARED_3D (srcvector) 
DOUBLE PRECISION srcvector (3) 

Lisp Syntax 

CMSR: fe-v-abs-squared-2d (src-vector) 

CMSR: fe-v-abs-squared-3d (src-vector) 


ARGUMENTS 

src_vector The vector for which the length squared is to be calculated. For 

CMSR_fe_v_abs_squared_2d src_vector is a 1 x 2 front-end 
array of double-precision values. For CMSR_f e_v_abs 
squared_3d it is a 1 x 3 array. 


Version 2.0, November 1991 


95 



*Render Reference Manual for Paris 


CMSR_fe_v_abs_squared_2d 

CMSR_fe_v_abs_squared_3d 


DESCRIPTION 

CMSR_fe_v_abs_squared_2d returns the square of the length of a 2D (1 x 2) 
srcjyector in front-end memory. 

CMSR_fe_v_abs_squared_3d returns the square of the length of a 3D (1 x 3) 
src vector in front-end memory. 


SEE ALSO 

CMSR_fe_v_abs_2d 
CMSR_fe_v_abs_3d 
CMS R_v_ab s_2 d 
CMSR_v_abs_3d 
CMSR_v_abs_squared_2d 
CMS R_v_ab s _s qu a r e d_3 d 
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C MS R_fe_v_add_2d 
CMSRJe_v_add_3d 


CMSR_fe_v_add_2d 

CMSR_fe_v_add_3d 

Performs element-wise addition of two vectors. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double * 

CMSR__fe__v_add__2d (srcl_vector, src2 vector, dest vector) 
double srcl vector[ 2] , src2 vector [ 2] , dest vector [ 2 ] ; 

double * 

CMSR_fe_v_add_3d (srcl vector, src2 vector, dest vector) 
double srcl vector [ 3 ] , src2 vector [3] , dest vector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_FE_V_ADD_2D (srcl vector, src2_vector, destvector) 
DOUBLE PRECISION srcl vector ( 2 ) , src2vector ( 2 ) , destvector ( 2 ) 

SUBROUTINE CMSR_FE_V_ADD_3D (srcl vector, src2 vector, destvector) 
DOUBLE PRECISION srcl vector ( 3) , src2vector ( 3 ) , dest vector ( 3 ) 


Lisp Syntax 

CMSR: fe-v-add-2d (srcl-vector src2-vector fioptional dest-vector) 
CMSR: fe-v-add-3d (srcl-vector src2-vector ^optional dest-vector) 
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ARGUMENTS 

srcl_yector, src2_vector 

One-dimensional arrays containing the vectors to be added. 

dest_yector A one-dimensional array containing the result of adding 

srcljyector and src2 vector. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. 

DESCRIPTION 

CMSR_fe_v_add_2d and CMSR_f e_v_add_3d do element-wise addition of the com¬ 
ponents of srcl vector and src2_yector and put the result in dest_yector. In C and Lisp 
this routine also returns a pointer to dest_vector. 

dest_vector may be the same as either srcl_vector or src2_vector. 

If a vector is a position vector, x occupies the first element, y occupies the second ele¬ 
ment, and z (if present) occupies the third element. 
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CNISR_fe_v_copy_2d 

CMSR_fe_v_copy_3d 


CMS R_fe_v_co py_2 d 
CMS R_fe_v_co py_3 d 

Copies one vector to another. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_v_copy_2d ( src_vector, destvector ) 
double src vector [2] , dest vector[2 ]; 

double * 

CMSR_fe_y_copy_3d ( srcvector, dest_vector) 
double src vector [ 3], dest_vector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE__V_COPY_2D ( src_vector, dest_vector) 
DOUBLE PRECISION src vector (2) , dest vector(2) 

SUBROUTINE CMSR_FE_V_COPY_3D ( src vector, dest vector) 
DOUBLE PRECISION src vector (3) , dest vector(3) 


Lisp Syntax 

CMSR: fe-v-copy-2d (src~vector fioptional dest-vector) 
CMSR: fe-v-copy-3d (src-vector &optional dest-vector) 
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CMSR_fe_v_copy_2d 

CMSR_fe_v_copy_3d 


ARGUMENTS 

src_vector A one-dimensional array containing the vector to be copied. 

destyector A one-dimensional array to which srcvector is to be copied. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. 

DESCRIPTION 

CMSR_fe_v_copy_2d and CMSR_f e_y_copy_3d copy srcvector to dest_vector. In 
C and Lisp a pointer is also returned to destyector. 

If a vector is a position vector, x occupies the first element, y occupies the second ele¬ 
ment, and z (if present) occupies the third element. 
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CMSR_fe_v_cosJ>etween_2d 
CMS R_fe__v_cos_between_3d 


CMS R_fe_v_cos_betwee n_2 d 
CMSR_fe_v_cos_between_3d 

Computes cosine of angle between two (three) vectors. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double 

CMSR_fe__v_cosJbetween_2d ( srcljvector, src2_yector) 
double srcl vector [ 2] , src2 vector [ 2 ] ; 

double 

CMSRjfe_v_cos_between_3d ( srcl vector, src2_yector) 
double srcl jyector [ 3 ] , src2_vector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR_FE_V_COSJBETWEEN_2D 

& (srcl jyector, src2jyector) 

DOUBLE PRECISION srcljyector( 2 ) , src2 vector ( 2 ) 

DOUBLE PRECISION FUNCTION CMSR_FE_V_COSJBETWEEN_3D 

& (srcljyector, src2_vector) 

DOUBLE PRECISION srcl jyector (3) , src2jyector ( 3) 


Lisp Syntax 

CMSR: fe-v-cos-between-2d (src-vectorl src-vector2) 
CMSR: fe-v-cos-between-3d (src-vectorl src-vector2) 
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CMSR_fe_v_cos_between_2d 

CMSR_fe_v_cos_between_3d *Render Reference Manual for Paris 


ARGUMENTS 

srcl_vector, src2_vector 

One-dimensional arrays containing the vectors. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays, x occupies element 0, y occupies 
element 1, and z (if present) occupies element 2. 


DESCRIPTION 

CMSR_£e_y_cos_between_2d and CMSR_fe_v_cos_between_3d return the co¬ 
sine of the angle between two vectors. This is the dot-product of the normalized 
vectors. The source vectors, srcl_vector and src2 vector, need not be unit length. 

Neither vector should be 0 length. 


ERRORS 

If either vector is of length 0, the result of this routine is undefined. 
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CMS R_fe_v_cross_prod u ct_3d 


CMS R_fe_v_cross_prod u ct_3d 

Calculates the cross-product of two 3D vectors. 


SYNTAX 
C Syntax 

#indude <cm/cmsr. h> 
double * 

CMSR_£e_v_cross_product_3d (srclvector, src2 vector, to_vector ) 

double srcl vector [ 3] ; 
double src2_vector[ 3] ; 
double to vector [ 3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cnisr-inath-f ort. h' 

SUBROUTINE CMSR_FE_V_CR0SS_PR0DUCT_3D (vectorl, vector2, to_vector) 

DOUBLE PRECISION srcl_vector{ 3) 

DOUBLE PRECISION src2 vector(3) 

DOUBLE PRECISION to_vector( 3) 


Lisp Syntax 

CMSR:fe-v-cross-product-3d 

(srcl-vector src2-vector soptional to-vector) 


ARGUMENTS 

srcl_vector, src2_vector 

1x3 arrays of double-precision numbers containing the vectors to 
be operated on. 

to_vector A 1 x 3 array in which the cross-product of srcl_vector and 

src2 vector is returned. 
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DESCRIPTION 

CMSR_fe_v_cross_product_3d calculates the cross-product between the 3-dimen- 
sional vectors srcljyector and src2_vector and stores the result in to_vector. 

In C and Lisp, CMSR_fe_v_cross_product_3d also returns a pointer to to_vector. 

SEE ALSO 

CMSR_cross_product_3d 


104 


Version 2.0, November 1991 




Chapter 3. Math Routines 


CMS R_fe_v_dot_prod u ct_2d 
CMS R_fe_v_dot_prod u ct_3d 


CMSR_fe_v_dot_product_2d 

CMSR_fe_v_dot_product_3d 

Returns the dot product of two 2D (3D) vectors. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double 

CMSR__fe__v__dot__produc t__2d (srcl vector, src2 vector) 

double srcl_vector[2] ; 

double src2_vector[ 2] ; 

double 

CMSR_fe_v__dot_j>roduct_3d (srcl vector, src2 vector) 

double srcl_yector[3] ; 

double src2_vector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR__FE__V_DOT__PRODUCT__2D 

& (srcl_vector r src2jyector) 

DOUBLE PRECISION src 1 _vector(2) 

DOUBLE PRECISION src2_vector(2) 

DOUBLE PRECISION FUNCTION CMSR_FEJVJDOT_PRODUCT_3D 

& (srcljvector, src2_vector) 

DOUBLE PRECISION srcl_vector(3) 

DOUBLE PRECISION src2_vector(3) 

Lisp Syntax 

CMSR: £e-v-dot-product-2d (src 1-vector src2-vector) 

CMSR: fe-v-dot-product-3d (srcl-vector src2-vector) 
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CMSR_fe_v_dot_product_2d 
CMSR_fe_v_dot_product_3d 


ARGUMENTS 

srcl_yector, src2_vector 

1x2 arrays of double-precision numbers containing the vectors to 
be operated on. 


DESCRIPTION 

CMSR_fe_v_dot._product._2d and CMSR_fe_v_dot_product_3d return the dot 
product of the two front-end vectors srcljyector and src2_vector. 


SEE ALSO 

CMSR_v_dot_product_2d 

CMSR_v_dot_product_3d 
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Chapter 3. Math Routines CMSR_fe_vJs_zero_3d 

CMS R_fe_vJ s_ze ro_2 d 
CMS R_fe_vJ s_ze ro_3 d 

Tests whether a vector is zero length. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
int 

CMSR_fe_v_is_zero_2d ( vector) 
double vector [ 2] ; 

int 

CMSR_fe_v_i s_z e ro_3 d ( vector) 
double vector 1 3]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
LOGICAL FUNCTION CMSR_FE_V_IS_ZERO_2D ( vector) 
DOUBLE PRECISION vector (2) 

LOGICAL FUNCTION CMSR_FE_V_IS_ZERO_3D ( vector) 
DOUBLE PRECISION vector (3) 


Lisp Syntax 

CMSR:fe-v-is-zero-2d ( vector) 
CMSR:fe-v-is-zero-3d ( vector ) 
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ARGUMENTS 

vector A one-dimensional array containing the vector to be tested. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. 


DESCRIPTION 

CMSR_fe_v_is_zero_2d and CMSR_f e_v_is_zero_3d test whether vector is zero 
length. If the given vector is of length 0, these routines return true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp). If the vector has length, these routines return false 
(.FALSE, in Fortran, NULL in C, nil in Lisp). 

The x coordinate occupies the first element, y occupies the second element, and z (if 
present) occupies the third element. 
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CMSR_fe_v_negate_2d 

CMSR_fe_vjiegate_3d 


CMS R_f e_v_n eg ate_2d 
CMSR_fe_v_negate_3d 

Multiplies each vector element by -1. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_v_negate_2 d ( src vector, destvector) 
double src_vector[ 2] , destvector [2] ; 

double * 

CMSR_fe_v_ne ga t e_3d ( src_vector, dest_vector) 
double src_vector[3], dest vector[3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR__FE_V__NEGATE_2D (src_yector t destjyector) 
DOUBLE PRECISION src_vector( 2) , dest_vector( 2) 

SUBROUTINE CMSR_FE_JV_NEGATE_3D (src_vector, destvector) 
DOUBLE PRECISION src vector (3) , dest vector(3) 


Lisp Syntax 

CMSR:fe-v-negate-2d(src-vecfor fioptional dest-vector) 
CMSR:£e-v-negate-3d(m?-vecfor Soptional dest-vector) 
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CMSR_fe_v_negate_3d 


^Render Reference Manual for Paris 


ARGUMENTS 

src_vector A one-dimensional array containing the vector to be negated. 

dest_vector A one-dimensional array containing the result of negating 

src_vector. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. 

DESCRIPTION 

CMSR_f e_v_negate_2d and CMSR_fe_v__negate_3d multiply each vector element 
by -1 and put the result in dest_vector. In C and Lisp these routines also return a point¬ 
er to dest vector. 

If a vector is a position vector, x occupies the first element, y occupies the second ele¬ 
ment, and z (if present) occupies the third element. 
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CMSR_fe_v_normalize__2d 
CMSR fe v normalize 3d 


CMSR_fe_v_normalize_2d 

CMSR__fe__v_normalize_3d 

Normalizes a vector to a unit vector. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe__v_normalize__2d (srcvector, destjyector) 
double src vector[2] , dest_yector[2] ; 

double * 

CMSR_fe_v__normalize_J3d (src vector, destjyector) 
double src_yector[ 3] , dest vector[3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_FE_V_NORMALI ZE_2D ( src_vector, dest_vector) 
DOUBLE PRECISION srcjyector (2) , destjyector (2) 

SUBROUTINE CMSR_FE_V_NORMALIZEJ3D (src_vector, dest_vector) 
DOUBLE PRECISION src_vector( 3) , destvector (3) 


Lisp Syntax 

CMSR:fe-v-normalize-2d (src-vector fioptional dest-vector) 
CMSR: fe-v-normalize-3d (src-vector ^optional dest-vector) 
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ARGUMENTS 

src_vector A one-dimensional array containing the vector to be normalized. 

dest_vector A one-dimensional array containing the result of normalizing 

src_vector. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays, x occupies element 0, y occupies 
element 1, and z (if present) occupies element 2. 


DESCRIPTION 

CMSR_f e_v_no rma 1 i z e_2 d and CMSR_fe_v_normalize_3d compute a unit vec¬ 
tor pointing in the same direction as src_vector and put the result in destvector. In C 
and Lisp these routines also return a pointer to dest vector. 

The source vector should not be zero length. 


ERRORS 

If the src vector is zero length, the behavior of this routine is undefined. 
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CMSR_fe_v_perpendicular_2d 

CMSR_fe_v_perpendicular_3d 


CMSR_fe_v_perpendicular_2d 

CMSR__fe_v_perpendicular_3d 

Constructs a unit vector perpendicular to one 2D or to two 3D vectors. 


SYNTAX 
C Syntax 

♦include <cm/cmsr.h> 
double * 

CMSR_f e__vj?erpendi cular_2 d (srcvector, dest vector) 
double src vector [ 2] , dest_yector[ 2] ; 

double * 

CMSR_fe__v_perpendicular_3d (srcl vector, src2 vector, dest vector) 
double srcl vector [3] , src2 vector\ 3] , dest vector [3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR__FE_V_PERPENDICULAR_2D ( src vector, destvector) 
DOUBLE PRECISION src_vector (2) , destvector (2) 

SUBROUTINE CMSR__FE_V__PERPENDICULAR__3D 

& (srcl vector, src2_vector, destvector) 

DOUBLE PRECISION srcl vector (3) , src2 vector (3) , destvector (3) 


Lisp Syntax 

CMSR: fe-v-perpendicular-2d (src 1-vector fioptional dest—vector) 

CMSR: £e-v-perpendicular-3d 

(srcl-vector src2-vector ^optional dest-vector) 
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ARGUMENTS 

src-vector, src-vectorl, src-vector2 

One-dimensional arrays containing the vectors to be operated on. 

dest_vector A one-dimensional array containing the result of the routine. 

For the 2D routine these are 2-element arrays; for the 3D routine these are 3-element 
arrays, x occupies element 0, y occupies element 1, and z (if present) occupies 
element 2. 


DESCRIPTION 

CMSR_fe_vjperpendicular_2d constructs a unit vector perpendicular to src_ 
vector, and puts the result in dest_vector. In C and Lisp this routine also returns a point¬ 
er to dest_vector. 

The source vector need not be unit length, but src_vector should not be zero length. 

CMSR_fe_vjperpendicular_3d constructs a unit vector perpendicular to srcl_ 
vector and src2 vector and puts the result in dest vector. In C and Lisp this routine also 
returns a pointer to dest_vector. The source vectors need not be unit length. 

The cross-product of the source vectors should not be zero length. 
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CMSR_fe_v_print_2d 

CMSR_fe_v_print_3d 


CMSR__fe_v_print_2d 
CMS R_fe_v_p ri n t_3d 

Prints the vector on stdout. 


SYNTAX 
C Syntax 

♦include <cm/cmsr.h> 
double * 

CMSR__fe_vjpr in t_2d (srcvector) 
double src_vector[2] ; 

double * 

CMSR_fe__vjpr in t__3d ( src_yector ) 
double src_yector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE__V_PRINT_2D ( src_vector) 
DOUBLE PRECISION src_yector (2) 

SUBROUTINE CMSR_FE_VJPRINT_3D (src_vector) 
DOUBLE PRECISION src_yector( 3) 


Lisp Syntax 

CMSR: f e-v-print-2d ( src-vector) 
CMSR: fe-v-print-3d ( src-vector) 
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CMSR_fe_v_print_2d 

CMSR_fe_v_print_3d 


ARGUMENTS 

src_vector A one-dimensional array containing the vector to be printed. 

For the 2D routine this is a 2-element array; for the 3D routine this 
is a 3-element array, x occupies element 0, y occupies element 1, 
and z (if present) occupies element 2. 

DESCRIPTION 

CMSR_fe_v_print_2d and CMSR_f e_v_print_3d print the srcjyector on stdout. 
In C and Lisp these routines also return a pointer to src_vector. 

The elements of the vector are printed on one line, separated by spaces, and followed 
by a carriage return. 
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CMSR_fe_v_reflect_2d 

CMSR_fe_v_ref!ect_3d 


CMSR_fe_v_reflect_2d 
CMS R_fe_v_ref lect_3d 

Calculates a reflectance vector for specified incident and normal vectors. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double * 

CMSR_fe__v_reflect_2d (incident vector, normal vector , dest vector) ; 
double incident vector[2] , normal vector[2] , dest_vector[2 ] ; 

double * 

flect_3d (incident_yector, normaljyector, destjyector) ; 
double incident vector[3] , normal vector[3] , dest_vector[3] ; 


Fortran Syntax 

INCLUDE '/usr/include/on/ansr-math-fort.h' 

SUBROUTINE CMSR_FE_V_REFLECT_2D 

& (incident vector, normal_yector ; dest vector) 

DOUBLE PRECISION incidentjyector (2) , normal vector(2) , dest_vector(2) 

SUBROUTINE CMSR_FE_V_REFLECT_3D 

& (incidentjvector, normal vector, destjyector) 

DOUBLE PRECISION incidentjyector (3), normal vector(3) , dest vector (3) 


Lisp Syntax 

CMSR: fe-v-reflect-2d (incident-vector normal-vector 

fioptional dest-vector) 

CMSR : fe-v-reflect-3d ( incident-vector normal-vector 

fioptional dest-vector) 
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ARGUMENTS 

incident^vector A one-dimensional array containing the vector indicating the 

direction of the incident light. 

normal_vector A one-dimensional array containing the vector indicating the 
normal vector of the surface from which the light is to reflect. 

dest_yector A one-dimensional array containing the vector indicating the 

direction of the reflected light. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays, jc occupies element 0, y occupies 
element 1, and z (if present) occupies element 2. 


DESCRIPTION 

CMSR_fe_v_reflect_2d and CMSR_fe_v_reflect_3d determine the vector re¬ 
sulting from reflecting incident vector around normal vector and put the result in 
dest_vector. In C and Lisp these routines also return a pointer to dest vector. The inci¬ 
dent and normal vectors need not be unit length, but the reflected vector will be. 

Neither input vector should be zero length. 

To build the destination vector, the incident and normal vectors are first normalized. 
The reflected vector (R), is then constructed from the unit-length incident vector (I) 
and unit-length normal (N) vector: 

R = 1-2 *(N dot I)*N 


normal_yector (N) 

A 



incident_vector (I) VI / destjyector (R) 
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C MS Rje_v_scalej2d 
C MS R_fe_v_scale__3d 


CMSR_fe_v_scale_2d 

CMSR_fe_v_scale_3d 

Multiplies a vector by a constant scale value. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr .h> 
double * 

CMSR_f e__v_js cal e__2d (src vector, scale value, dest vector) 
double src vector[2] , scale_yalue, dest_vector[2 ] ; 


double * 

CMSR_fe_v_s cal e_J3d ( src_yector , scalejvalue, destjyector) 
double src vector[3] , scale value , dest vector [3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-niath-fort .h' 

SUBROUTINE CMSRJETI_V_SCALE_2D (srcvector, scale value , dest vector) 
DOUBLE PRECISION src_vector( 2) , scale_value, dest vector (2) 

SUBROUTINE CMSR__FE__V__SCALE__3D (src_vector, scale value, destjyector) 
DOUBLE PRECISION src_vector{ 3) , scale_yalue, destvector (3) 


Lisp Syntax 

CMSR: fe-v-scale-2d (src-vector scale-value l optional dest-vector) 
CMSR: fe-v-scale-3d (src-vector scale-value Soptional dest-vector) 
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CMSR_fe_v_scale_2d 

CMSR_fe_v_scale_3d 


ARGUMENTS 

srcvector A one-dimensional array containing the vector to be scaled. 


scale_value The scaling factor to be applied to srcjyector. 

dest_yector A one-dimensional array containing the result of scaling 

src_vector by the scale_value. 

For the 2D routine the arrays contain 2 elements; for the 3D 
routine the arrays contain 3 elements, x occupies element 0, y 
occupies element 1, and z (if present) occupies element 2. 


DESCRIPTION 

CMSR_fe_v_scale_2d and CMSR_fe_v_scale_3d multiply each element of 
src vector by the constant scale value and put the result in dest_yector. In C and Lisp, 
these routines also return a pointer to destvector. 

destvector may be the same as src vector. 
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CMS R_fe_v_s u bt ract_2d 
CMS R_fe_v_s u bt ract_3d 


CMSR_fe_v_subtract_2d 
CMS R_fe_v_s u b t ract_3 d 

Subtracts each element of one vector from another. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_v_subtract_2d (srcljvector, src2_vector, dest vector) 
double srcl_yector[ 2] , src2 vector [ 2] , dest vector [2] ; 

double * 

CMSR_fe_v_subtract_3d (srcl vector, src2 vector, dest vector) 
double srcl vector[3] , src2 vector [ 3] , dest_yector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math~fort.h' 

SUBROUTINE CMSR_FE_V_SUBTRACT_2D 

& (srcl vector, src2jyector, dest vector) 

DOUBLE PRECISION srcl jyector (2) , src2_vector(2) , dest vector(2) 

SUBROUTINE CMSR_FE_VJSUBTRACT_3D 

& (srcl jyector, src2_vector, dest_vector) 

DOUBLE PRECISION srcl_vector(3), src2vector (3) , destjyector(3) 


Lisp Syntax 

CMSR: fe-v-subtract-2d (srcl-vector src2-vector & optional dest-vector) 
CMSR:fe-v-subtract-3d (srcl-vector src2-vector fioptional dest-vector) 
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ARGUMENTS 

srcl_vector, src2_vector 

One-dimensional arrays containing the vectors to be subtracted. 

dest_vector A one-dimensional array containing the result of subtracting 

srcl_vector and src2_vector. 

For the 2D routine the arrays contain 2 elements; for the 3D 
routine the arrays contain 3 elements, jc occupies element 0, y 
occupies element 1, and z (if present) occupies element 2. 


DESCRIPTION 

CMSR_fe__v_subtract_2d and CMSR_fe_v_subtract_3d subtract each element 
of src2_vector from srcl_yector ( srcl_vector - src2_vector ) and put the result in 
dest_vector. In C and Lisp these routines also return a pointer to dest vector. 

dest_yector may be the same as srcljvector or src2_vector. 
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Chapter 3. Math Routines CMSR_fe_v_transform_3d 

CMSR_fe_v_transform_2d 

CMSR_fe_v_transform_3d 

Returns vector transformed by transformation matrix. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_v_t r ansform__2d (srcjyector, srcjnatrix, destjyector) 

double src_vector[ 2] ; 
double srcjnatrix [3] [3] ; 

double dest_vector [ 2 ] ; 

double * 

CMSRjfe__v_t r an s form_3d (srcjyector, srcjnatrix, destjyector) 

double srcjyector \3\ ; 

double srcjnatrix [4] [4] ; 
double destjyector [3] ; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_FE_V__TRANSF0RM_2D 

& (src vector, srcjnatrix, destjyector) 

INTEGER srcjyector (2 ) 

INTEGER srcjnatrix (3,3) 

INTEGER destjyector (2 ) 

SUBROUTINE CMSR_FE_V_TRANSF0RM_3D 

& (srcjyector, srcjnatrix , destjyector) 

INTEGER srcjyector (3 ) 

INTEGER srcjnatrix (4,4) 

INTEGER dest_vector (3 ) 
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Lisp Syntax 

CMSR:fe-v-transform-vector-2d 

(src-vector src-matrix fioptional dest-vector) 

CMSR:fe-v-transform-vector-3d 

(src-vector src-matrix fioptional dest-vector) 


ARGUMENTS 

src vector 


src matrix 


dest vector 


For CMSR_f e_v_trans f orm _2 d a 1 x 2 array, and for CMSR_ 
fe_v_transform_3d a 1 x 3 array containing the vector to be 
transformed. 

For CMSR_f e_v_tran s f orm_2 d a 3 x 3 array, and for CMSR_ 
f e_v_transf orm_3d a 4 x 4 array containing the homogeneous 
transformation matrix to be applied to src vector. The matrix 
elements are stored in row- major order. 

For CMSR_f e_v_trans f orm_2d a 1 x 2 array, and for CMSR_ 
fe_v_transform_3d a 1 x 3 array containing the transformed 
vector. 


DESCRIPTION 

CMSR_fe_v_trans form_2d and CMSR_fe_v_transform_3d calculate the result 
of transforming the vector src_vector by the homogeneous transformation matrix 
srcjnatrix and store the result in dest_vector. destjyector may be the same as src_ 
vector. 

In C and Lisp, these routines also return a pointer to dest_vector. In Lisp dest_vector is 
optional; space for the vector is allocated if it is not specified. 


ERRORS 

If the homogeneous coordinate of the transformed vector goes to zero, the result of this 
routine is undefined. 
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SEE ALSO 

CMSR_v_transform_2d 
CMSR_v_t rans form_3d 
CMS R_v_t r an s f o rm_c o n s t_2 d 
CMSR v transform const 3d 
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CMSR_fe_v_transmit_3d 

Creates a transmittance vector for light refracted through two materials. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_f e_v_tran smi t_3 d 

(incident Rector, normalvector, indexl, index2, transmittedvector) 

double incidentjyector [ 3 ], normal vector [3]; 

double indexl, index2 ; 
double transmittedjvector[ 3] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_FE_V_TRANSMIT_3d 

& (incident vector, normal_vector, indexl, index2, transmitted vector) 

DOUBLE PRECISION incidentjvector (3), normal vector (3) 

DOUBLE PRECISION indexl, index2 
DOUBLE PRECISION transmitted_vector ( 3 ) 


Lisp Syntax 

CMSR:fe-v-transmit-3d ( incident-vector normal-vector indexl index2 

Soptional transmitted-vector) 


ARGUMENTS 

incident vector A one-dimensional array of 3 elements containing the vector 
indicating the direction of the incident light, x occupies element 0, 
y occupies element 1, and z (if present) occupies element 2. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. 
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CMSR_fe_v_transmit_3d 


normal vector A one-dimensional array of 3 elements containing the vector 
indicating the surface normal of the material through which the 
light is to pass, x occupies element 0, y occupies element 1, and z 
(if present) occupies element 2. 

indexl, index2 The index of refraction of the medium containing incident vector 

and transmitted vector, respectively. 

transmitted vector A one-dimensional array of 3 elements containing the vector 
indicating the direction of the transmitted light, x occupies 
element 0, y occupies element 1, and z (if present) occupies 
element 2. 


DESCRIPTION 

CMSR_fe_v_transmit_3d, given an incident vector, surface normal, and indices of 
refraction for the two materials, constructs a transmitted light vector and puts the vec¬ 
tor in transmitted vector. In C and Lisp this routine also returns a pointer to 
transmittedvector. 

The unit length transmitted vector T is given by: 


T = 


th 

«2 


1+ N 


— (N --D- 

\ «2 



(N --1)2-1 


N is the unit vector in the direction of normal vector. I is the unit vector in the direction 
of incident vector, nl is indexl, the index of refraction of the medium containing the 
incident vector. n2 is index2, the index of refraction of the medium which contains the 
transmitted vector. 


normal vector (N) 

\ 

incidentjyector (I) 


\t 

d)^ 


incident medium 


\ 


transmittance medium 
transmitted_vector (T) 
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CMSR fe v transmit 3d 


If the expression under the square root becomes negative, the result is total internal 
reflection. If total internal reflection occurs, CMSR_fe_v_transmit_3d returns a 
NULL pointer. 

Neither the incident vector nor the normal vector should be length 0. The second index 
of refraction should not be 0. 
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3.3 Front-end Matrix Routines 

This section documents the *Render routines that operate on matrices in front-end arrays. 
Matrices in ^Render are assumed to be square, homogeneous matrices. * Render supports 
matrices of dimension 2 or 3, for transforming two-dimensional or three-dimensional vec¬ 
tors. On the front end, a matrix is an appropriately sized array of double-precision 


floating-point values. 

The routines documented here are: 

CMSR_fe_identityjnaatrix_2d . 131 

CMSR_fe_identity_matrix_J3d . 131 

CMSR_fejm_copy_2d . 133 

CMSR_fe__m_copy_J3d . 133 

CMSR_fejmjietenriinant_2d. 135 

CMSR_fe_m_determinant__3d. 135 

CMSR_fe_m_invert_2d. 137 

GMSR_fe_m_invert_3d. 137 

O^R_fe_m_multiply_2d . 139 

C^R_fejnajmultiply_3d . 139 

C^R_fe_m_print_2d. 141 

CMSR_fe_m_jprintJ3d. 141 

CMSR_fe_oblique_proj_matrix . 143 

CMSR_fe_ortdio_pro j jmatrix. 145 

CMSR^fe^jperspectivejmatrix . 147 

CMSR_fe_j?erspective_proj_matrix . 149 

CMSR_fe_rotationjnaatrix_2d . 151 

CMSR_fe_scale_matrix_2d. 153 

CMSR_fe__scale_matrix_3d. 153 

CMSR_fe_translationjmatrix_2d. 155 

C^dSR_fe_translation_matrix_3d. 155 

CMSR_fe_yiew__matrix. 157 

CMSR_fe_view_^roj_matrix. 159 
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QiSR_fe_x_rotation_matrix_3d.. 161 

CMSR_fe_y_rotationjcnatrix_3d. 161 

CMSR fe z rotation matrix 3d. 161 


130 


Version 2.0, November 1991 






Chapter 3. Math Routines 


CMSR_feJdentity_matrix_2d 

CMSR_fe_identity_matrix_3d 


CMSR_fe_identity_matrix_2d 

CMSR_feJdentity_matrix_3d 

Creates 2D (3D) homogeneous transformation identity matrix in front-end array. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_identity_matrix_2d ( destjnatrix) 
double destjnatrix [3] [3] ; 

double * 

CMSR_fe_identity_matrix_3d ( destjnatrix) 
double destjnatrix [4] [4]; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort. h' 
SUBROUTINE CMSR_FE_IDENTITY_MATRIX_2D (destjnatrix) 
DOUBLE PRECISION destjnatrix (3,3) 

SUBROUTINE CMSR_FE_IDENTITY_MATRIX_3D (destjnatrix) 
DOUBLE PRECISION destjnatrix (4,4) 

Lisp Syntax 

CMSR: fe-identity-matrix-2d (Soptional dest-matrix) 
CMSR: fe-identity-matrix-3d (Soptional dest-matrix) 


ARGUMENTS 

destjnatrix A 3 x 3 array for CMSR_fe_identity_matrix_2d or a 4 x 4 

array for CMSR_fe_identity_matrix_3d into which a 
homogeneous identity matrix is stored. The matrix elements are 
stored in row-major order. 
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CMSR_fe_identlty_matrix_2d 

CMSR_fe_identity_matrix_3d 


DESCRIPTION 

CMSR_fe_identity_matrix_2d and CMSR_fe_identity_matrix_3d set the 
front-end matrix destjnatrix to an identity matrix for 2D or 3D homogeneous trans¬ 
formations. 

In C and Lisp, the routines also return a pointer to dest jnatrix. In Lisp, dest-matrix is 
optional; space is allocated if the matrix is not specified. 

The identity matrix is the identity element for matrix multiplication. It is an array in 
which all elements are set to 0 except for the diagonal elements, which are set to 1. 


SEE ALSO 

CMSR_identity_matrix_2d 

CMSR_identity_matrix_3d 
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C MS R_fe_m_copy_2d 
CMSR_fe_m_copy_3d 


CMSR_fe_m_copy_2d 

CMSR_fe_m_copy_3d 

Copies 2D (3D) transformation matrix between front-end arrays. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_m_copy_2d ( fromjnatrix, to matrix) 

double from_matrix[3] [3] ; 
double to matrix [ 3] [3] ; 

double * 

CMSR_fe_m_copy_3d ( fromjnatrix, tojnatrix) 

double from matrix [4] [4]; 
double tojnatrix1 4] [4] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE_M_COPY_2D (from matrix, to matrix) 

DOUBLE PRECISION from matrix ( 3,3) 

DOUBLE PRECISION tojnatrix (3,3) 

SUBROUTINE CMSR_FE_M_COPY_3D ( fromjnatrix, tojnatrix) 

DOUBLE PRECISION fromjnatrix (4,4) 

DOUBLE PRECISION to matrix (4,4) 


Lisp Syntax 

CMSR:fe-m-copy-2d (from-matrix Soptional to-matrix) 
CMSR:fe-m-copy-3d (from-matrix &optional to-matrix) 
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CMSR_fe_m_copy_2d 

CMSR_fe_m_copy_3d 


ARGUMENTS 

fromjnatrix 

For CMSR_fa_m_copy_2d a 3 x 3 array, or for CMSR_fe_m_ 
copy_3d a 4 x 4 array containing the homogeneous 
transformation matrix to be copied. The matrix elements are 
stored in row-major order. 

tojnatrix 

For CMSR_fe_m__copy_2d a 3 x 3 array, or for CMSR_fe_m_ 
copy_3d a 4 x 4 array into which fromjnatrix is to be copied. 
The matrix elements are stored in row-major order. 


DESCRIPTION 

CMSR_fe_m_copy_2d and CMSR_fe_m_copy_3d copy the front-end matrix 
fromjnatrix to the front-end matrix tojnatrix. 

In C and Lisp, CMSR_fe_m_copy_2d and CMSR_fe_m_copy_3d also return a pointer 
to to matrix. In Lisp, from-matrix is optional; space is allocated for the matrix if it is 
not specified. 
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CMSR_fe_m_determinantJ2d 

CMSR_fejri_determinant_3d 


CMSR_fe_m_determinant_2d 

CMSR_fe_m_determinant_3d 

Returns the determinant of a matrix. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double 

CMSR_fe_m_determinant_2d ( matrix) 
double matrix[ 3] [3]; 

double 

CMSR_fe_m_determinant_3d ( matrix) 
double matrix [ 4] [4]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR_FE_M_DETERMINANT_2D (matrix) 
DOUBLE PRECISION matrix (3,3) 

DOUBLE PRECISION FUNCTION CMSR_FE_M_DETERMINANT_3D ( matrix) 
DOUBLE PRECISION matrix (4,4) 

Lisp Syntax 

CMSR:fe-m-determinant-2d ( matrix) 

CMSR: fe-m-determinant-3d ( matrix) 


ARGUMENTS 

matrix For CMSR_fe_m_determinant_2d a 3 x 3 array, or for CMSR_ 

fe_m_determinant_3d a 4 x 4 array, containing a 
homogeneous transformation matrix. The matrix elements are 
stored in row-major order. 
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DESCRIPTION 

CMSR_fe_m_determinant_2d and CMSR_fe_m_determinant_3d return the 
determinant of the matrix specified in matrix. 
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CMSR_fe_mJnvert_2d 

CMSR_fe_m_invert_3d 


CMSR_fe_m_i n vert_2d 
CMSR_fe_m_i n vert_3d 

Creates the inverse of a 2D (3D) matrix using arrays on the front-end computer. 


SYNTAX 

C Syntax 

#include <cm/cmsr. h> 
double * 

CMSR_fe_m_invert_2d {fromjnatrix, tomatrix)) 
double from matrix [3] [3] , to matrix[3] [3] ; 

double * 

CMSR_fe_m_invert_3d (frommatrix, to matrix) 
double from matrix [4] [4] , to matrix [ 4] [4] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE_M_INVERT_2D ifromjnatrix, to matrix) 
DOUBLE PRECISION fromjnatrix (3, 3), tojnatrix( 3, 3) 

SUBROUTINE CMSR_FE_M_INVERT_3D {from matrix, to matrix) 
DOUBLE PRECISION fromjnatrix { 4, 4), tomatrix (4 , 4) 


Lisp Syntax 

CMSR: fe-m-invert-2d (from-matrix Soptional to-matrix) 
CMSR: fe-m-invert-3d (from-matrix Soptional to-matrix) 
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ARGUMENTS 

fromjnatrix An array containing the transformation matrix to be inverted. For 

the 2D routine this is a 3 x 3 array of homogeneous coordinates; 
for the 3D routine this is a 4 x 4 array. The matrix elements are 
stored in row-major order. 

tojnatrix An array into which the inverted from jnatrix is to be copied. For 

the 2D routine this is a 3 x 3 array of homogeneous coordinates; 
for the 3D routine this is a 4 x 4 array. The matrix elements are 
stored in row-major order. 


DESCRIPTION 

CMSR_fe_m_invert_2d and CMSR_fe_m_invert_3d place the inverse of 
fromjnatrix in tojnatrix. The destination matrix, tojnatrix, may be identical to the 
source matrix fromjnatrix. If the matrix is singular (that is, if its determinant is zero), a 
fatal error occurs. 

In C and Lisp, these routines also return a pointer to to matrix. In Lisp, to-matrix is 
optional; space is allocated if the matrix is not specified. 


ERRORS 

If the matrix is singular (that is, if its determinant is zero), a fatal error occurs. 

SEE ALSO 

CMSR_m_inv er t_2d 
CMSR m invert 3d 
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CMSR_fe_m_multfply_2d 
CMSR_fe_m_multiply_3d 

CMSR_fe_m_multiply_2d 

CMSR_fe_m_multiply_3d 

Multiplies two 2D (3D) transformation matrices. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_m_multiply_2d (srcljnatrix, src2 matrix, destjnatrix) 

double srcl matrix [ 3] [3]; 
double src2jnatrix [3] [3] ; 
double destjnatrix [3] [3] ; 

double * 

CMSR_fe_m_multiply_3d (srcl matrix, src2 matrix, destjnatrix) 

double srcl matrix [ 4] [4]; 
double src2 matrix [ 4] [4] ; 
double dest matrix [ 4] [4]; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort. h' 

SUBROUTINE CMSR_FE_M_MULTIPLY_2D 
& (srcjnatrixl srcjnatrix2 destjnatrix) 

DOUBLE PRECISION srcljnatrix (3, 3) 

DOUBLE PRECISION src2jnatrix (3, 3) 

DOUBLE PRECISION destjnatrix (3, 3) 

SUBROUTINE CMSR_FE_M_MULTIPLY_3D 
& (srcjnatrixl src_matrix2 destjnatrix) 

DOUBLE PRECISION srcljnatrix (4, 4) 

DOUBLE PRECISION src2jnatrix (4, 4) 

DOUBLE PRECISION destjnatrix (4, 4) 

Lisp Syntax 

CMSR:fe-m-multiply-2d (srcl-matrix src2-matrix Soptional dest-matrix) 
CMSR:fe-m-multiply-3d (src 1-matrix src2-matrix fioptional dest-matrix) 
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CMSR_fe_m_multiply_3d 


ARGUMENTS 

srcl jnatrix, src2_matrix 

For CMSR_fe_m_multiply_2d 3x3 arrays, and for 
CMSR_fe_m_multiply_3d 4x4 arrays, containing the 
homogeneous transformation matrices to be multiplied. The 
matrix elements are stored in row-major order. 

destjnatrix For CMSR_fe_m_multiply_2d a 3 x 3 array, and for 

CMSR_fe_m_multiply_3d a 4 x 4 array, in which the product of 
srcl jnatrix and srcl jnatrix is returned. The matrix elements are 
stored in row-major order. 


DESCRIPTION 

CMSR_fe_m_multiply_2d and CMSR_f e_m_multiply_3d calculate the product of 
two homogeneous transformation matrices, ( src-matrixl* src-matrixT) and store the 
result in destjnatrix. The destination matrix may be the same as either source matrix. 

In C and Lisp, these routines also return a pointer to destjnatrix. In Lisp dest-matrix is 
optional; space is allocated for the matrix if it is not specified. 


SEE ALSO 

CMSR_m_multiply_2d 

CMSR_m_multiply-3d 

CMS R_m_mu11ip1y_cons t_2d 

CMSR_m_multiply_const_3d 
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CMSR_fe_m_print_2d 

CMSR_fe_m_print_3d 


CMS R_fe_m_p ri n t_2d 
CMSR_fe_m_print_3d 

Prints the contents of a matrix on stdout. 


SYNTAX 
C Syntax 

#indude <cm/cmsr. h> 
double * 

CMSR_fe_m_pri n t_2 d ( srcjnatrix) 
double src matrix [ 3] [3] ; 

double * 

CMSR_fe_m_jprint_3d (src matrix) 
double src matrix [ 4] [4]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE_M_PRINT_2D ( srcjnatrix) 
DOUBLE PRECISION src matrix (3, 3) 

SUBROUTINE CMSR_FE_M_PRINT_3D ( srcjnatrix) 
DOUBLE PRECISION srcjnatrix (4, 4) 

Lisp Syntax 

CMSR: fe-m-print-2d ( src-matrix ) 

CMSR: fe-m-print-3d (src-matrix) 
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ARGUMENTS 

srcjnatrix The front-end array to be printed. 

For CMSR_f e_m_prin t_2 d src-matrix is a 3 x 3 array. 
For CMSR_fe_m_print_3d src-matrix is a 4 x 4 array. 


DESCRIPTION 

CMSR_fe_m_print_2d and CMSR_fe_m_print_3d print the double-precision float¬ 
ing-point contents of the srcjnatrix array on stdout. The matrix elements are printed 
one row per line, separated by spaces, and followed by a carriage return. 

In C and Lisp these routines also return a pointer to srcjnatrix. 


SEE ALSO 

CMSR_m_p r i n t_2d 

CMSR_m_p r i n t_3d 


142 


Version 2.0, November 1991 


Chapter 3. Math Routines 


CMSR_fe_oblique_proj_matrix 


CMS R_fe_o b I i q u e_p rojmat r ix 

Creates an oblique projection matrix for a specified angle and foreshortening. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_oblique_proj_matrix (foreshortenting, angle, destjnatrix) 

double foreshortening; 

double angle; 

double destjnatrix [4]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_FE_OBLIQUE_PROJ_MATRIX 

& (foreshortenting, angle, destjnatrix) 

DOUBLE PRECISION foreshortening; 

DOUBLE PRECISION angle; 

DOUBLE PRECISION destjnatrix (4, 4) ; 


Lisp Syntax 

CMSR:fe-oblique-proj-matrix 

(foreshortenting angle soptional dest-matrix) 


ARGUMENTS 

foreshortenting The ratio of the projected length of a line in z, to its true 
length.The length of a projected z-axis unit vector. 

angle The angle between the projected z-axis and the true horizontal of 

the object. 
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destjnatrix A 4 x 4 front-end array containing a homogeneous transformation 

matrix that expresses the oblique projection defined by foreshort- 
enting and angle. 


DESCRIPTION 

CMSR_fe_oblique_pro j_matrix builds an oblique projection matrix and stores it 
in destjnatrix. In C and Lisp, this routine also returns a pointer to destjnatrix. 

An oblique projection is one in which the parallel projectors intersect with the projec¬ 
tion plane at an oblique angle. In this routine, angle is the angle that the projected z-axis 
makes with the horizontal. The projection is onto the plane z = 0. Foreshortening is the 
length of a projected z-axis unit vector. When foreshortening is 0, an orthographic 
projection results. 
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CMSR_fe_ortho_proj_matrix 


CMSR_fe_ortho_proj_matrix 

Creates an orthographic projection matrix perpendicular to a specified plane. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_ortho_pro j_matrix (axis, destmatrix) 

int axis: 

double dest matrix [4] [4] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_FE_ORTHO_PROJ_MATRIX (axis, dest matrix) 
INTEGER axis 

DOUBLE PRECISION dest matrix (4, 4) 


Lisp Syntax 

CMSR: fe-ortho-proj-matrix (axis Soptional dest-matrix) 


ARGUMENTS 

axis The axis that will be the plane of projection, axis may be specified 

either symbolically or with an integer: 

■ x axis = CMSR_x or 0 

■ y axis = CMSR^y or 1 

■ z axis = CMSR_z or 2 

destjnatrix A 4 x 4 front-end array containing a homogeneous transformation 

matrix that expresses an orthographic projection onto axis. 
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DESCRIPTION 

CMSR_fe_orthojproj_matrix builds an orthographic projection matrix and 
stores it in destjnatrix. In C and Lisp this routine also returns a pointer to destmatrix. 

An orthographic projection is a perpendicular projection onto one of the coordinate 
planes. This projection is commonly used for engineering drawings. 

In this routine, the axis parameter determines the plane of projection: 

If axis is CMSR_x or 0, then the plane of projection is x = 0. 

If axis is CMSR_y or 1, then the plane of projection is y = 0. 

If axis is CMSR_z or 2, then the plane of projection is z = 0. 

If axis is not one of the above, a fatal error results. 


ERRORS 

If axis is not CMSR_x (0) , CMSR_y (1), or CMSR_z (2), a fatal error results. 
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CMSR_fe_perspective_matrix 


CMSR_fe_perspective_matrix 

Creates a perspective transformation matrix. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double * 

CMSR_fe_j?erspective_matrix (axis, center of_proj, destjnatrix) 

int axis; 

double center_of_proj; 

double destjnatrix [ 4 ] [ 4 ] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-f ort.h' 

SUBROUTINE CMSR_FE_PERSPECTIVE__MATRIX 

& (axis, center ofjproj, destjnatrix) 

INTEGER axis 

DOUBLE PRECISION center ofj?roj 
DOUBLE PRECISION destjnatrix (4, 4) 


Lisp Syntax 

CMSR: f e-perspective-matrix 

(axis center-of-proj fioptional dest-matrix) 


ARGUMENTS 

axis The axis that will be the plane of projection, axis may be specified 

either symbolically or with an integer: 

■ x axis = CMSR_x or 0 

■ y axis = CMSR_y or 1 

■ z axis = CMSR__z or 2 

If axis is not one of the above, a fatal error results. 
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center_of_proj 


dest matrix 


DESCRIPTION 

CMSR_£e_perspective_matrix builds a perspective transformation matrix and 
stores it in dest matrix. In C and Lisp, this routine also returns a pointer to dest matrix, 
axis specifies the axis of projection, center_position is the center of projection along 
axis. 

When the completed perspective transformation is applied to object coordinates, object 
size is reduced with increasing distance from the center of the projection. 

Note that CMSR_fejperspective_matrix creates a matrix that maps from one 3D 
space into another 3D space. To transform an object for drawing into a two-dimension¬ 
al image buffer, you must concatenate a projection matrix to this perspective matrix. 


Specifies the point on axis on which the projection is to be 
centered. 

If center of_proj is zero, a fatal error results. 

A 4 x 4 front-end array containing the homogeneous transforma¬ 
tion matrix created by the routine. 


ERRORS 

A fatal error results if axis is not CMSR_x (0) , CMSR_y (1), or CMSR_z (2) or if 
center of_proj is zero. 
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CMSR_fe_perspective_proj_matrix 


CMSR__fe_perspective__proj_matrix 

Creates a transformation matrix composed of a perspective transformation and an orthogo¬ 
nal projection. 


SYNTAX 
C Syntax 

♦include <cm/cmsr.h> 
double * 

CMSR__fe_perspective_proj_matrix {axis, center of_proj, destjnatrix) 

int axis; 

double center of_proj; 

double dest matrix [4] [4] ; 


Fortran Syntax 


INCLUDE '/usr/include/cm/cmsr-math-fort.h' 


& 


SUBROUTINE CMSR_FEJPERSPECTIVE_PROJJMATRIX 

(axis, center_of_proj, destjnatrix) 


DOUBLE PRECISION 
DOUBLE PRECISION 
DOUBLE PRECISION 


axis 

center ofjproj 
destjnatrix (4, 


4) 


Lisp Syntax 

CMSR:fe-perspective-proj-matrix 

(axis center-of-proj ^optional dest-matrix) 


ARGUMENTS 

axis The axis that will be the plane of projection, axis may be specified 

either symbolically or with an integer: 

■ x axis = CMSR_x or 0 

■ y axis = CMSR_y or 1 

■ z axis = CMSR_z or 2 

If axis is not one of the above, a fatal error results. 
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center_of_proj Specifies the point on axis on which the projection is to be 

centered. 

If center_of_proj is zero, a fatal error results. 

destjnatrix A 4 x 4 front-end array containing the homogeneous transforma¬ 

tion matrix created by the routine. 


DESCRIPTION 

CMSR_fe_perspective__proj_matrix builds a transformation matrix that is a 
composition of a perspective transformation centered on center of_proj and an ortho¬ 
gonal projection along the axis specified by axis. This transformation matrix is placed 
in destjnatrix. In C and Lisp, this routine also returns a pointer to destjnatrix. 

The axis parameter determines the plane of projection. 

If axis is CMSR_x or 0, then the plane of projection is x = 0. 

If axis is CMSR_y or 1, then the plane of projection is y = 0. 

If axis is CMSR_z or 2, then the plane of projection is z = 0. 


ERRORS 

A fatal error results if axis is not CMSR_x (0), CMSR_y (1), or CMSR_z (2) or if center_ 
ofjxroj is zero. 
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CMSR_fe_rotation_matrix_2d 


CMSR_fe_rotation_matrix_2d 

Creates a 2D transformation matrix with a specified rotation in a front-end array. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_rotation_matrix_2d (theta, destjnatrix) 

double theta; 

double destjnatrix [3] [3]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMS R_FE_ROTAT I ON_MATR I X_2 D (theta, destjnatrix) 

DOUBLE PRECISION theta 

DOUBLE PRECISION destjnatrix (3,3) 


Lisp Syntax 

CMSR:fe-rotation-matrix-2d (theta Soptional dest-matrix) 


ARGUMENTS 

theta A double-precision value specifying the the angle of rotation, in 

radians, to be incorporated into the transformation matrix in 
destjnatrix. 

destjnatrix A 3 x 3 array in which the resulting 2D transformation matrix is 

returned. The matrix elements are stored in row-major order. 
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DESCRIPTION 

CMSRjfe_rotationjmatrix_2d calculates a two-dimensional homogeneous trans¬ 
formation matrix with a rotation of theta radians and places the result in destjnatrix. 

In C and Lisp, CMSR_£e_rota tion_matrix_2d also returns a pointer to dest_ 
matrix . In Lisp destjnatrix is optional; space is allocated if the matrix is not specified. 

The rotation is about the origin of the image. Positive rotations are counter-clockwise. 


SEE ALSO 

CMSR_fe__x__rotation_matrix_3d 

CMSR_fe__y__rotation__matrix_3d 

CMSR__fe_z_rotation__matrix_3d 

CMSR_rotation_matrix_2d 

(3iSR_rotation_constjnatrix__2d 

CMSR_x__r o tation_con s t_matrix_J3d 

CMSR_x_rotation_matrix_3d 

CMSR__y_rotation_const_matrix__3d 

CMSR^y^rotation^matrix^Sd 

CMSR_jz__rotation_cons t_matrix_J3d 

CMSR z rotation matrix 3d 


152 


Version 2.0, November 1991 




Chapter 3. Math Routines 


CMSR_fe_scalejnatrixJ2d 

CMSRJe_scale_matrix__3d 


CMSR_fe_scale_matrix_2d 

CMSR_fe_scale_matrix_3d 

Creates a 2D (3D) transformation matrix with specified scaling values in a front-end array. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_scale__mat r ix__2d (sx, sy, destjnatrix) 

double sx, sy; 

double destjnatrix [ 3 ] [ 3 ] ; 

double * 

CMSR_fe_scale_matrix__3d (sx, sy, sz, destjnatrix) 

double sx, sy, sz; 
double destjnatrix [ 4 ] [ 4 ] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE C^R_FE_SCALE_MATRIX__2D (sx, sy, destjnatrix) 

DOUBLE PRECISION SX, sy 
DOUBLE PRECISION destjnatrix (3,3) 

SUBROUTINE CMSR_FE_SCALE_MATRIX_3D (SX, sy, SZ, destjnatrix) 

DOUBLE PRECISION SX, sy. SZ 
DOUBLE PRECISION destjnatrix (4,4) 


Lisp Syntax 

CMSR:£e-scale-matrix-2d (sx sy fioptional dest-matrix) 
CMSR:fe-scale-matrix-3d (sx sy sz ^optional dest-matrix) 
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ARGUMENTS 

sx 


sy 


sy 


destjnatrix 


A double-precision value specifying the x coordinate scaling 
value to be incorporated into the transformation matrix in 
destjnatrix. 

A double-precision value specifying the y coordinate scaling 
value to be incorporated into the transformation matrix in 
destjnatrix. 

A double-precision value specifying the z coordinate scaling value 
to be incorporated into the transformation matrix in destjnatrix. 

A 3 x 3 array for CMSR_fe_scale_matrix_2d, or a 4 x 4 array 
for CMSR_fe_scale_matrix_3d, in which the resulting 
transformation matrix is returned. The matrix elements are stored 
in row-major order. 


DESCRIPTION 

CMSR_fe_scale_matrix_2d calculates a two-dimensional homogeneous transfor¬ 
mation matrix with the scaling terms sx and sy. CMSR_fe_scale_matrix_3d 
calculates a three-dimensional transformation matrix with the scaling terms sx, sy, and 
sz. The scaling matrix is stored in destmatrix. 

In C and Lisp these routines also return a pointer to dest matrix. In Lisp dest-matrix is 
optional; space is allocated if the matrix is not specified. 


SEE ALSO 

CMSR_scale_const_matrix_2d 
CMSR_scale_const__matrix_3d 
CMSR_scale_matrix_2d 
CMSR scale matrix 3d 
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CMSR_fe__translation._matrix._2d 

CMSR_fe_translation_matrix_3d 


CMSR_fe_translation_matrix_2d 

CMSR_fe_translation_matrix_3d 

Creates a 2D (3D) transformation matrix in a front-end array with specified translation 
values. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR__fe_translation_matrix__2d (tx, ty, destjnatrix) 

double tx, ty; 

double destjnatrix [ 3 ] [ 3 ] ; 

double * 

CMSR_fe_translation_matrix_3d (tx, ty, tz, destjnatrix) 

double tx, ty, tz; 

double destjnatrix [4] [4] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cansr-math-fort.h' 

SUBROUTINE CMSR_JTE_JTRANSLATION_MATRIX_2D (tx, ty, destjnatrix) 

DOUBLE PRECISION tx, ty 
DOUBLE PRECISION destjnatrix(3,3) 

SUBROUTINE CMSR_FE_TRANSLATION_MATRIX_3D (tx, ty, tz, destjnatrix) 

DOUBLE PRECISION tx, ty, tz 
DOUBLE PRECISION destjnatrix (4 , 4) 


Lisp Syntax 

CMSR: fe-translation-matrix-2d (tx ty &optional dest-matrix) 
CMSR: fe-translation-matrix-3d (tx ty tz &optional dest-matrix) 
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ARGUMENTS 

tx 

ty 

tz 


destjnatrix 


A double-precision value specifying the x translation value to be 
incorporated into the transformation matrix in destjnatrix. 

A double-precision value specifying the y translation value to be 
incorporated into the transformation matrix in destjnatrix. 

A double-precision value specifying the z translation value to be 
incorporated into the transformation matrix in destjnatrix. 

A 3 x 3 array for CMSR_fe_translation_matrix_2d or a 4 x 
4 array for CMSR_fe_translation_matrix_3d, in which the 
resulting transformation matrix is returned. The matrix elements 
are stored in row-major order. 


DESCRIPTION 

CMSR_fe_translation_matrix_2d and CMSR_fe_translation_matrix_3d 
calculate a 2D or 3D transformation matrix, respectively, which translates homoge¬ 
neous coordinate values by tx, ty, and, in the 3D case, tz. The matrix is stored in the 
front-end matrix destjnatrix. 

In C and Lisp, these routines also return a pointer to destjnatrix. In Lisp dest-matrix is 
optional; space is allocated for the matrix if it is not specified. 


SEE ALSO 

CMSR_translation_const_matrix_2d 
CMSR_translation_const_matrix_3d 
CMSR_translation_matrix_2d 
CMSR translation-matrix-3d 
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CMSR_fe_view_matrix 


CMSR_fe_view__matrix 

Creates a viewing transformation matrix. 


SYNTAX 
C Syntax 

#include <can/eras r. h> 
double * 

CMSR_fe_view_matrix ( eyevector, look_atj>ector, roll, viewjnatrix) 

double eye_vector[ 3] ; 
double lookjatvector [ 3 ] ; 
double roll; 

double viewjnatrix [ 4 ] [ 4 ] ; 


Fortran Syntax 


INCLUDE ' /usr/include/cm/emsr-math-fort. h' 


& 


INTEGER FUNCTION CMSR_FE_VIEW_MATRIX 

(eye_vector, look_at_vector, roll, viewjnatrix) 


DOUBLE PRECISION 
DOUBLE PRECISION 
DOUBLE PRECISION 
DOUBLE PRECISION 


eyevector (3) 
look_at_yector (3) 
roll 

viewjnatrix ( 4, 4) 


Lisp Syntax 

CMSR:fe-view-matrix 

(eye—vector look-at-vector &optional (roll 0) view-matrix) 


ARGUMENTS 

eye_vector A one-dimensional, 3-element, position vector: x occupies 

element 0, y occupies element 1, and z occupies element 2. The 
viewjnatrix created transforms this point to the negative z axis. 
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CMSR fe view matrix 


look_at_vector A one-dimensional, 3-element, position vector: x occupies 
element 0, y occupies element 1, and z occupies element 2. The 
viewjnatrix created transforms this point to the origin of the 
viewing space. 

roll The amount of rotation about the z axis to be included in the 

viewjnatrix transformation. 

viewjnatrix 

An array containing the completed view transformation matrix. 
For the 2D routine this is a 3 x 3 array of homogeneous 
coordinates; for the 3D routine this is a 4 x 4 array. The matrix 
elements are stored in row-major order. 


DESCRIPTION 

CMSR_fe_view_matrix builds a viewing transformation matrix, puts it in view_ 
matrix, and returns a pointer to viewjnatrix. This matrix transforms the coordinate 
space defined by eyevector, lookjitjyector, and roll so that the lookatvector 
position is at the origin and the eye_vector position is on the negative z axis. 

The roll argument allows you to specify how much this coordinate space should be 
rotated around the z axis. Each of the vectors must be of dimension 3 and the view_ 
matrix must be 4 x 4. 

ERRORS 

If eye_vector is identical to look at vector, a fatal error results because the view can 
not be determined. 

SEE ALSO 

CMSR_fe_view_proj_matrix 
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CMSR_fe_view_proj_matrix 

CMSR_fe_view_proj_matrix 

Creates a viewing transformation matrix. 

SYNTAX 
C Syntax 

#±nclude <cm/cmsr ,h> 
double * 

CMSR__fe__view_proj_matrix 

( centerjfjroj, eye_vector, look_at_vector, roll , destjnatrix) 

double centerjofjproj; 

double ey ejector [ 3] ; 

double lookatjector [3] ; 
double roll; 

double destjnatrix [4] [4]; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_FE_VIEW_PROJ___MATRIX 

& (centerjfjroj, eyevector, look_atjector y roll , destjnatrix) 

DOUBLE PRECISION center jfjroj 
DOUBLE PRECISION eye_vector( 3) 

DOUBLE PRECISION lookjtjector (3) 

DOUBLE PRECISION roll 

DOUBLE PRECISION destjnatrix (4, 4) 

Lisp Syntax 

CMSR: f e-view-pro j -matrix 

(eye-vector look-at-vector ^optional (roll 0) dest-matrix) 
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ARGUMENTS 

center_of_proj Specifies the point on the z axis on which the projection is to be 

centered. 

If center_of_proj is zero, a fatal error results. 

eyejyector A one-dimensional, 3-element, position vector: x occupies 

element 0, y occupies element 1, and z occupies element 2. The 
viewjnatrix created transforms this point to the negative z axis. 

lookatvector A one-dimensional, 3-element, position vector: x occupies 
element 0, y occupies element 1, and z occupies element 2. The 
viewjnatrix created transforms this point to the origin of the 
viewing space. 

roll The amount of rotation about the z axis to be included in the 

view matrix transformation. 

destjnatrix A 4 x 4 front-end array containing the homogeneous transforma¬ 

tion matrix created by the routine. 


DESCRIPTION 

CMSR_f e_view_pro j_matrix returns a pointer to a matrix that is a composition of a 
viewing transformation defined by eyevector, lookatvector, and roll, with a per¬ 
spective projection along the z axis centered on center_of_proj. 

This matrix transforms the coordinate space defined by eye vector, lookatjvector, 
and roll so that the lookatvector position is at the origin and the eye_vector position 
is on the negative z axis and then projects this transformation onto the z axis at the 
plane located at center of_proj. 


ERRORS 

A fatal error results if eye_vector is identical to look_at_vector or if center_of_proj is 
zero. 
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CMSR_fe_x_rotation_matrix_3d 
CMS R_fe_y_rotat i o n_m a t r ix_3 d 
CMSR_fe_z_rotation_matrix_3d 

Creates, in a front-end array, a 3D transformation matrix with a specified rotation about the 
x (y, z) axis. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_x_ro ta tion_ma tr ix_3d ( theta, dest matrix) 
double * 

CMSR_y__rotation__matrix_3d (theta, destmatrix) 
double * 

CMSR_z_rotation_matrix__3d (theta, dest matrix) 

double theta; 

double dest_matrix[ 4] [4] ; 


Fortran Syntax 


INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_XJ&OTATION_MATRIXJ3D (theta, 
SUBROUTINE CMSR_Y_ROTATION_MATRIX_3D (theta, 
SUBROUTINE CMSRJZ_ROTATIONJMATRIX_3D (theta, 

DOUBLE PRECISION theta 

DOUBLE PRECISION dest_matrix( 4,4) 


destjnatrix) 

destjnatrix) 

destmatrix) 


Lisp Syntax 

CMSR:x-rotation-matrix-3d (theta ^optional dest-matrix) 
CMSR:y-rotation-matrix-3d (theta ^optional dest-matrix) 
CMSR: z-rotation-matrix-3d (theta fioptional dest-matrix) 
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CMSR_fe_y_rotation_matrix_3d 
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ARGUMENTS 

theta 


destjnatrix 


DESCRIPTION 

CMSR_£e_x_rotation_matrix_3d, CMSR_fe_y_rotation_matrix_3d, and 
CMSR_fe_z_rotation_matrix_3d calculate a three-dimensional transformation 
matrix with a rotation of theta radians around the x, y, or z axis and store it in dest_ 
matrix. Positive rotations are counter-clockwise as you look down the axis from the 
origin. 

In C and Lisp, these routines both return a pointer to the resulting matrix and also place 
the result in destjnatrix. In Lisp dest-matrix is optional; space is allocated if the 
matrix is not specified. 


A double-precision value specifying the the angle of rotation 
about the axis, in radians, to be incorporated into the transforma¬ 
tion matrix in destjnatrix. 

A 4 x 4 array in which the resulting 3D homogeneous transforma¬ 
tion matrix is returned. The matrix elements are stored in 
row-major order. 


SEE ALSO 

CMSR_fe_rotation_matrix_2d 
CMSR_rotation_matrix_2d 
CMSR_rotation_cons t_matrix_2d 
CMSR_x_rotation_const_matrix_3d 
CMSR_x_rotation_matrix_3d 
CMSR_y__rotation_const_matrix_3d 
CMSR_y_rotation_matrix_3d 
CMSR_z_rotation_cons t_ma trix_3d 
CMSR z rotation matrix 
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3.4 Front-End Color Conversion 

This section documents the new *Render routines that convert color vectors between color 


spaces. 

CMSR_fe_rgb_to_cmy. 164 

CMSR_fe_cmy_to_rgb. 164 

CMSR_£e_rgb_to_yiq. 166 

CMSR_fe_yiq_to_rgb. 166 

CMSR_fe_rgb_to_hsv. 168 

OdSR_£e_hsv_to_rgb. 168 

CMSR_fe_rgb_to_hsl. 170 

CMSR__fe_hsl_to_rgb. 170 
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CMSR_fe_rgb_to_cmy 

CMSR_fe_cmy_to_rgb 


CMS R_fe_rg b_to_c my 
C MS R_fe_cmy_to_rg b 

Converts color vector from RGB to CMY (CMY to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_jfe_r gb___t o__cmy (rgbvector, cmy vector) ; 
double rgb_vector[ 3] , cmy vector [3] ; 

double * 

CMSR__fe__cmy_to_rgb (cmy vector, rgb vector) ; 
double cmy_yector [3] , rgbjvector [3]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_FE__RGB_TO_CMY (rgbvector, cmy vector) 
DOUBLE PRECISION rgbjvector ( 3) , cmy_vector( 3) 

INTEGER FUNCTION CMSR_FE_CMY_jTO_RGB (cmy_vector, rgbjyector) 
DOUBLE PRECISION cmy_vector( 3), rgb_vector(3) 


Lisp Syntax 

CMSR: fe-rgb-to-cmy (rgb-vector Soptional cmy-vector) 
CMSR:fe-cmy-to-rgb (cmy-vector fioptional rgb-vector) 
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CMSR_fe_rgb_to_cmy 

CMSR_fe_cmy_to_rgb 


ARGUMENTS 

rgbvector A one-dimensional array of 3 elements containing an RGB color 

triplet. The red intensity is in the first element, the green intensity 
is in the second element, and the blue intensity is in the third 
element. Each of the RGB color components should be in the 
range of [0,1]. 

cmy_vector A one-dimensional array of 3 elements containing a CMY color 

triplet. The cyan intensity is in the first element, the magenta 
intensity is in the second element, and the yellow intensity is in the 
third element. Each of the CMY color components should be in the 
range of [0,1]. 

DESCRIPTION 

CMSR_fe_rgb_to_cmy converts the RGB triplet in rgb vector to CMY triplet, places 
the result in cmy vector, and returns a pointer to cmy vector. The relationship is 

(c,m,y) = (1,1,1) - (r,g,b) 

CMSR_fe_cmy_to_rgb converts the CMY triplet in cmy vector to RGB, places the 
result in rgb vector and returns a pointer to rgb_yector. The relationship is 

(r,g,b) = (1,1,1) - (c,m,y) 
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CMS R_fe_rg b_t o_y i q 
CMS R_fe_y i q_t o_rg b 

Converts color vector from RGB to YIQ (YIQ to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_rgb_to_yiq {rgbvector, yiqjvector) 
double rgbvector [ 3 ] , yiq vector [ 3] ; 

double * 

CMSR_fe_yiq_to_rgb {yiq vector, rgb vector) 
double yiq vector[3], rgb_vector[3 ] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_FE_RGB_TO_YIQ {rgb vector, yiq vector) 
DOUBLE PRECISION rgb vector{3) , yiq vector{3) 

INTEGER FUNCTION CMSR_FE_YIQ_TO_RGB {yiq_vector, rgb vector) 
DOUBLE PRECISION yiq_vector(3) , rgb_yector{3) 


Lisp Syntax 

CMSR:fe-rgb-to-yiq (rgb-vector Soptional yiq—vector) 
CMSR:fe-yiq-to-rgb (yiq-vector Soptional rgb-vector) 
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CMSR_fe_rgb_to_yiq 

CMSR_fe_yiq_to_rgb 


ARGUMENTS 

rgb_yector A one-dimensional array of 3 elements containing an RGB color 

triplet. The red intensity is in the first element, the green intensity 
is in the second element, and the blue intensity is in the third 
element. Each of the RGB color components should be in the 
range of [0,1]. 

yiq_yector A one-dimensional array of 3 elements containing a YIQ color 

triplet. 


DESCRIPTION 

CMSR_fe_rgb_to_yiq converts an RGB triplet in rgbvector to a YIQ triplet, places 
the result in yiq_vector, and returns a pointer to yiq vector. Each of the RGB color 
components should be in the range [0,1]. 

CMSR_fe_yiq^to_rgb converts a YIQ triplet in yiq_vector to an RGB triplet, places 
the result in rgb vector, and returns a pointer to rgb_vector. Each of the YIQ color com¬ 
ponents should be in the range [0,1] but this restriction is not enforced. 
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CMS R_fe_rg b_to_h s v 
CMS R_fe_h s v_t o_rg b 

Converts a color vector from RGB to HSV (HSV to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_rgb_to_hsv (rgbvector, hsv vector) 
double rgb_vector[ 3], hsv_vector[ 3] ; 

double * 

CMSR_fe_hsv_to_rgb (hsvjyector, rgb_vector) 
double hsv_yector [3] , rgb_vector[ 3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cansr-math-fort.h' 

SUBROUTINE CMSR_fe_rgb_to_hsv (rgb vector, hsv vector) 
DOUBLE PRECISION rgb_vector( 3) , hsv_vector( 3) 

SUBROUTINE CMSR_fe_hsv_to_rgb (hsv_vector, rgb_vector) 
DOUBLE PRECISION hsv vector (3) , rgb vector (3) 


Lisp Syntax 

CMSR:fe-rgb-to-hsv (rgb-vector & optional hsv-vector) 
CMSR:fe-hsv-to-rgb (hsv-vector & optional rgb-vector) 
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CMSR_fe_rgb_to_hsv 

CMSR_fe_hsv_to_rgb 


ARGUMENTS 

rgb_vector A one-dimensional array of 3 elements containing an RGB color 

triplet. The red intensity is in the first element, the green intensity 
is in the second element, and the blue intensity is in the third 
element. Each of the RGB color components should be in the 
range of [0,1]. 

hsv_vector A one-dimensional array of 3 elements containing an HSV color 

triplet. The hue of the color is in the first element, the saturation 
is in the second element, and the value is in the third element. Hue 
should be in the range [0, 2*pi], and saturation and value should 
be in the range [0,1]. 


DESCRIPTION 

CMSR_fe_rgb_to_hsv converts the RGB triplet in rgb_vector to HSV, places the re¬ 
sult in hsvvector, and returns a pointer to hsv_vector. Hue will be between 0.0 and 
2*pi. If s is zero, h is irrelevant and is set to zero. If v is zero, h and s are irrelevant and 
are also set to zero. 

CMSR_fe_hsv_to_rgb converts the HSV triplet in hsv vector to an RGB triplet, 
places the result in rgbvector and returns a pointer to rgbvector. Hue is taken modulo 
2*pi. If s is zero, h is irrelevant. If v is zero, s and v are irrelevant. 
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CMSR_fe_rgb_to_hsl 

CMSR_fe_hsl_to_rgb 


CMS R_fe_rg b_t o_h s I 
CMS R_fe_h s l_t o_rg b 

Converts a color vector from RGB to HSL (HSL to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_rgb_to_hsl ( tgbvector, hslvector) 
double rgb vector[3], hsl_vector[3 ] ; 

double * 

CMSR_fe_hsl_to_rgb ( hsljvector, rgb_vector) 
double hsl_vector[3], rgb_yector[3 ]; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 
SUBROUTINE CMSR_fe_rgb_to_hsl ( rgb_vector, hsl_vector) 
DOUBLE PRECISION rgb_vector(3), hsv_yector (3) 

SUBROUTINE CMSR_FE_HSL_TO_RGB (hsv vector, rgb vector) 
DOUBLE PRECISION hsv vector{3), rgbjvector (3) 


Lisp Syntax 

CMSR:fe-rgb-to-hsl (rgb-vector & optional hsv-vector ) 
CMSR:fe-hsl-to-rgb (hsv-vector & optional rgb-vector) 
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CMSR_fe_rgb_to_hsl 

CMSR_fe_hsl_to_rgb 


ARGUMENTS 

rgb_vector A one-dimensional array of 3 elements containing an RGB color 

triplet. The red intensity is in the first element, the green intensity 
is in the second element, and the blue intensity is in the third 
element. Each of the RGB color components should be in the 
range of [0,1]. 

hsl_vector A one-dimensional array of 3 elements containing an HSL color 

triplet. The hue of the color is in the first element, the saturation 
is in the second element, and the lightness is in the third element. 
Hue should be in the range [0,2*pi], and saturation and lightness 
should be in the range [0,1]. 


DESCRIPTION 

CMSR_fe_rgb_to_hsl converts the RGB triplet in rgb_vector to an HSL triplet and 
places the result in hsl_vector. CMSR_fe_hsl_to_rgb converts the HSL triplet in 
hsl_yector to an RGB triplet and places the result in rgb vector. 

In C and Lisp these routines also return a pointer to the result vector. 

If saturation is zero, the resulting color is a gray shade. In this case hue is irrelevant and 
is set to zero. If lightness is zero, the color is black. In this case both hue and saturation 
are irrelevant and are set to zero. 


Version 2.0, November 1991 


171 


*Render Reference Manual for Paris 


3.5 Front-End Miscellaneous Routines 

This section contains utility routines to convert between degrees and radians: 


CMSR_fe_deg_to_rad... 173 

CMSR_fe_rad_to_deg.. 173 
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CMSR_fe_deg_to_rad 

CMSR_fe_rad_to_deg 


CMSR_fe_deg_to_rad 

CMSR_fe_rad_to_deg 

Converts degrees to radians (radians to degrees). 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
double 

CMSR_fe_deg__t o_r ad ( value ) 
double value; 

double 

CMSR_fe_rad__to_deg ( value ) 
double value; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

DOUBLE PRECISION FUNCTION CMSR_FEJDEGJTO_RAD (value) 
DOUBLE PRECISION value 

DOUBLE PRECISION FUNCTION FSRJ&E_RADJTO_DEG (value) 
DOUBLE PRECISION value 


Lisp Syntax 

CMSR: fe-deg-to-rad (value) 
CMSR: fe-rad-to-deg (value) 


ARGUMENTS 

value The value to be converted. 


Version 2.0, November 1991 


173 



*Render Reference Manual for Paris 


CMS R _fe_d eg_to_rad 
CMSR_fe_rad_to_deg 


DESCRIPTION 

CMSR_fe_deg_to_rad accepts the argument value, in degrees, and returns it 
expressed in radians. 

CMSR_fe_rad_to_deg accepts the argument value, in radians, and returns it 
expressed in degrees. 


174 


Version 2.0, November 1991 




Chapter 3. Math Routines 


3.4 Front-End Color Conversion 

This section documents the new *Render routines that convert color vectors between color 
spaces. 

CMSR_fe_rgb_to_cmy. 164 

C^R_fe_cmy_to_rgb. 164 

CMSR_fe_rgb_to_yiq. 166 

C^R_fe^iq_to_rgb. 166 

CMSR_fe_rgb_to_hsv. 168 

CMSR_fe_hsv_to_rgb. 168 

CMSR_£e__rgb__to_hsl . 170 

CMSR_fe__hsl_to_rgb. 170 
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CMS R_fe_rg b_to_c my 
CMS R_fe_cmy_to_rg b 

Converts color vector from RGB to CMY (CMY to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_fe_rgb_to_cmy ( rgb vector, cmy_yector) ; 
double rgb vector [ 3], cmy vector [ 3] ; 

double * 

CMSR_fe_cmy_to_rgb (cmyjvector, rgb_vector) ; 
double cmy_yector [ 3 ] , rgb vector [ 3] ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_FE_RGB_TO_CMY [rgb vector, cmy vector) 
DOUBLE PRECISION rgb vector (3) , cmy vector (3) 

INTEGER FUNCTION CMSR_FE_CMY_TO_RGB [cmy vector, rgb vector) 
DOUBLE PRECISION cmy_vector[ 3) , rgb vector[3) 


Lisp Syntax 

CMSR:fe-rgb-to-cmy [rgb-vector & optional cmy-vector) 
CMSR:fe-cmy-to-rgb [cmy-vector fioptional rgb-vector) 
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3.6 CM Vector Routines 

This section documents the ^Render routines that operate on vectors in Paris fields in CM 
memory. Vectors in ♦Render are one-dimensional arrays of either two or three elements. 

On the CM, each vector is a single field of (dimension)* (signifjen+expjen+l) bits, where 
signifjen is the length of the significand, exp Jen is the length of the exponent, and the 1 
is for a sign bit. Each element of the vector occupies a subfield of (signifjen+expjen+l) 
bits, and these subfields are arranged so that element 0 is in the least significant bits. 


The routines documented here are: 

CMSR _ v _ abs J 2d . 177 

CMSR_vjabsJ3d . 177 

C^R_v_abs_squared_2d . 179 

CMSRjv_absjsquared_3d . 179 

CMSRjr^add^d. 181 

CMSRjrjzddJSd . 181 

CMSR_y__al 1 oc_jtieap_£ie 1 d_2d . 183 

CMSR_v_alloc_heapj£ield__3d . 183 

CMSR_v_alloc_stack_field_j2d . 185 

C^R_v_alloc_stack_field_3d . 185 

CMSR_v__copy_2 d. 187 

(34SR_v_copy_3d. 187 

O^R_y_copy_const_2d. 189 

CMSR_jv_copy__cons t_3d... 189 

CMSR_v_cos_between_2d . 192 

C^R_v_cos__betweenJ3d . 192 

C^R_v_cross_product_3d. 195 

CMSR_v_dot_product_2d . 197 

CMSR_v_do t_produ c t_3 d . 197 

CMSR__v_fi e ld_length. 200 

CMSR v is zero 2d . 202 
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CMSR_v_is_zero_3d . 

CMSR_v_negate_2d. 

CMSR_v_negate_3d. 

CMSR_v_normalize_2d . 

CMSR_v_normalize_3d . 

CMSR_v_jpe rpendi cu 1 ar_2 d. 

CMSR_y_perpendicular_3d . 

CMSR_v_print_2d . 

CMSR_v_print_3d . 

CMSR_v_read_from_processor_2d 

CMSR_v_read_froin_processor_3d 

CMSR_v_reflect_2d . 

CMSR_v_reflect_3d . 

CMSR_v_ref_x . 

CMSR_v_ref_y . 

CMSR_v_ref_z . 

CMSR_v_scale_2d . 

CMSR_y_scale_3d . 

CMSR_v_scale_const_2d __ 

CMSR_v_scale_const_3d . 

CMSR_v_subtract_2d . 

CMSR_v_subtract_3d. 

CMSR_v_transform_2d . 

CMSR_v_transform_3d. 

CMSR_v_transform_const_2d . 

CMSR_v_transform_const_3d. 

CMSR_v_transmi t_3d. 

CMSR_y_write_to_processor_2d . 
CMSR_v_write_to_jprocessor_3d . 
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CMSR_v__abs_2d 
CMSR_v_abs_3d 

Calculates the length of a 2D (3D) vector. 

SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR_y_abs__2d (destJield, src_vectorJield, signifjen, exp Jen) 

void 

CMSR_v_abs_3d (destJield\ srcjvectorJield, signifjen, exp len field) 

CM_field___id__t destJeld; 

CM_field__id__t srcjvectorJeld; 
unsigned int signifjen ; 
unsigned int exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/onsr-math-fort.h' 

CMSR_V_ABS_2D ( destJeld, srcvectorJeld, signifjen, exp Jen) 
CMSR__V_ABS_3D (destJeld, srcvectorJeld, signifjen, exp len field) 

INTEGER destJeld 
INTEGER src_vectorJeld 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR: v-abs-2d (destJeld src-vectorjeld 

fioptional ( signif-len 23) (exp-len 8) ) 

CMSR: v-abs-3d (dest Jeld src-vector-field 

Soptional (signif-len 23) (exp-len 8)) 


CMSR_v_abs_2d 

CMSR_v_abs_3d 
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CMSR_v_abs_2d 

C MSR_v_abs_3d ^ ^Render Reference Manual for Paris. 

ARGUMENTS 

destJield A Paris field identifier specifying the field in CM memory to 

which the result is written, dest Jield must be in the same VP set 
as src_vectorJield. 

src_vectorJield A Paris field indentifier specifying the field containing the vector. 

Each element has a length of ( signifjen + exp Jen + 1) bits. 

For CMSR_v_abs_2d the vector contains two floating-point 
values organized so that x occupies the least significant bits andy 
the most significant bits. The length of the entire field is 2 * 

(signifjen + exp Jen +1) 

For CMSR_v_abs_3d the vector contains three floating-point 
values organized so that x occupies the least significant bits, y the 
following bits, and z the most significant bits. The length of the 
entire field is 3 * ( signifjen + exp Jen + 1) 

signifjen The length, in bits, of the significand of the floating-point values 

in dest Jield and src_vectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest Jield and srcjvector Jield. 


DESCRIPTION 

For each active processor, CMSR_v_abs_2d and CMSR_v_abs_3d calculate the length 
of the vector specified in src_vectorJield and write the result to dest Jield. The fields 
src_vector Jield and dest Jield must both be in the current VP set. 


SEE ALSO 

CMSR_v_abs_squared_2d 

CMSR_v_abs_squared_3d 

CMSR_fe_v_abs_2d 

CMSR_fe_v_abs_3d 

CMSR_fe_v_abs_s quared_2 d 

CMSR_fe_y_abs_squared_3d 
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CMSR_v_abs_squared_2d 

CMSR_v_abs_squared_3d 

Calculates the length squared of a 2D (3D) vector. 


SYNTAX 
C Syntax 

tinclude <cm/cmsr.h> 
void 

CMSR_v_abs_squared_2d 

(destJield, srcvectorJield, signifjen, exp Jen field) 

void 

CMSR_v_abs_squared_3d 

(destJield, srcvectorJield, signifjen, exp Jen field) 

CM_field_id_t destJield; 

CM_field_id_t src_vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_ABS_SQUARED_2D 

& (destJield, srcvectorJield, signifjen, exp Jen field) 

SUBROUTINE CMSR_V_ABS_SQUARED_3D 

& (destJield, srcjyectorJield, signifjen, exp Jen field) 

INTEGER destJield 
INTEGER srcvectorJield 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR : v-abs-squared-2d (destJield src-vectorJield 

{•optional (signif-len 23) (exp-len 8)) 

CMSR : v-abs-squared-3d (destJield src-vector Jield 

fioptional '(signif-len 23) (exp-len 8)) 
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CMSR_v_abs_squared_2d 

CMSR_v_abs_squared_3d 


ARGUMENTS 

destJield A Paris field identifier specifying the field in CM memory to 

which the result is written, dest Jield must be in the same VP set 
as src_vectorJield. 

srcvectorJield A Paris field indentifier specifying the field containing the vector. 

Each element has a length of ( signifjen + exp Jen + 1) bits. 

For CMSR_v_abs_squared_2d the vector contains two 
floating-point values organized so that x occupies the least 
significant bits and y the most significant bits. The length of the 
entire field is 2 * {signifjen + exp Jen + 1) 

For CMSR_v_abs_squared_3d the vector contains three 
floating-point values organized so that x occupies the least 
significant bits, y the following bits, and z the most significant 
bits. The length of the entire field is 3 * {signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in dest Jield and src_yector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest Jield and src_yector Jeld. 


DESCRIPTION 

For each active processor, CMS R_v_abs_squared_2d and CMSR_v_abs_squared 
_3d calculate the the length squared of the vector specified in src_vector Jeld and 
write the result to destJeld. src_vectorJield and destJield must both be in the current 
VP set 

SEE ALSO 

CMSR_v_abs_3d, CMSR__v_abs_3d 
CMSR_fe_v_abs_2d, CMSR_fe_v_abs_3d 

CMSR_fe_v_abs_squared_2d, CMSR_fe_v_abs_squared_3d 
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CMSR_v_add__2d 
CMSR_v_add__3d 

Adds 2D (3D) vectors element by element. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_add_2 d 

(dest_yectorJeld, srcl_vectorJield, src2_vectorJield, signifjen, exp Jen) 

void 

CMSR_v_add_3d 

(dest_yectorJield, srcljyectorJield, src2_vectorJeld, signifjen, exp Jen) 

CM_field_id_t dest_vectorJeld; 

CM_field_id_t srcl_vectorJeld; 

CM_field_id_t src2_vectorJeld; 
unsigned int signifjen; 
unsigned int exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_ADD_2D 

& ( dest_yectorJeld, srcl_vectorJeld, src2_vectorJeld, signifjen, exp Jen) 

SUBROUTINE CMSR_V_ADD_3D 

& (destvectorJield, srcl vectorJeld, src2_yectorJeld, signifjen, exp Jen) 

INTEGER dest_vectorJeld; 

INTEGER srclvectorJeld; 

INTEGER src2_vectorJeld; 

INTEGER signifjen; 

integer exp len; 


CMSR_v_add_2d 

CMSR_v_add_3d 
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Lisp Syntax 

CMSR:v-add-2d ( dest-vector-field src 1-vector-field src2-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR : v-add-3d ( dest-vector-field src 1-vector-field src2-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the vector field in CM memory 
to which the result is written, destvectorJield must be in the 
same VP set as srcl_vectorJield or src2 vector Jield. 

srcl vectorJield, src2_vectorJield 

Paris field indentifiers specifying the fields containing the vectors 
that are to be added. 

For CMSR_v_add_2d the vector fields contain two floating-point values organized so 
that x occupies the least significant bits and y the most significant bits. Each element 
has a length of ( signifjen + exp Jen +1) bits. The length of the entire field is 
2 * ( signifjen + exp Jen +1). 

For CMSR_v_add_3d the vector contains three floating-point values organized so that 
x occupies the least significant bits, y the following bits, and z the most significant bits. 
Each element has a length of C signifjen + exp Jen +1) bits. The length of the entire 
field is 3 * ( signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in destjvector Jeld, srcl_vector Jeld, and src2_vectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vectorJeld, srcl_vectorJeld, and src2_vectorJeld. 


DESCRIPTION 

For each active processor, CMSR_v_add_2d and CMSR_v_add_3d add each element 
of the vector specified in srcljvectorJeld to the corresponding element of src2_ 
vector Jeld and write the result to dest_yector Jeld. The fields srcl_vector Jeld, 
src2_yector Jeld, and dest_vector Jeld must be in the current VP set. 
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CMSR_v_alloc_heap_field_2d 

CMSR_v_alloc_heap_field_3d 

Allocates a vector field organized as a 2-element (3-element) array on the heap and return 
its Paris field ID. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 

CM_£ield_id_t 

CMSR_v_alloc_heap_field_2d ( signifjen, exp Jen) 
unsigned int signif len, exp len; 

CM_field_id_t 

CMSR_v_alloc_heap_field_3d ( signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

FUNCTION INTEGER CMSR_V_ALLOC_HEAP_FIELD_2D (signifjen, exp Jen) 
INTEGER signifjen, exp Jen; 

FUNCTION INTEGER CMSR_V_ALLOC_HEAP_FIELD_3D (signifjen, expjen) 
INTEGER signifjen, expjen; 

Lisp Syntax 

CMSR:v-alloc-heap-field-2d ( signif-len exp-len) 
CMSR:v-alloc-heap-field-3d ( signif-len exp-len) 
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CMSR_v_alloc_heap_field_3d 
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ARGUMENTS 

signifjen The length, in bits, of the significant! of the floating-point values 

to be stored in the returned field. 

exp Jen The length, in bits, of the exponent of the floating-point values to 

be stored in the returned field. 


DESCRIPTION 

CMSR_v_alloc_heap_field_2d and CMSR_v_alloc_heap_field_3d allocate a 
vector field on the heap and return its Paris field ID. 

A vector field is organized to contain an array of floating-point values. Each element of 
the vector has a length of ( signifjen + exp Jen +1), where signifjen is the length of 
the significant exp len is the length of the exponent, and 1 is the sign bit. 

CMSR_v_alloc_heap_field_2d allocates a field organized as a 2-element array. 
The length of the entire field is 2 * ( signifjen + exp Jen + 1). 

CMSR_v_alloc_heap_field_3d allocates a field organized as a 3-element array. 
The length of the entire field is 3 * {signifjen + exp len + 1). 

If the vector is a position vector, the field is organized so that x occupies the first ele¬ 
ment, y occupies the second element, and z (if present) occupies the third element. 
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CMSR_v__alloc_stack_field_2d 

CMSR_v_alloc_stackJield_3d 


CMSR_v_alloc_stack_field_2d 

CMSR_v_alloc_stack_field_3d 

Allocates a vector field organized as a 2-element (3-element) array on the stack and return 
its Paris field ID. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 

CM_field__id_t 

CMSR_v_alloc_stack_field_2d (signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 

CM_field_id_t 

CMSR_v_alloc_stack_field_3d ( signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

FUNCTION INTEGER CMSR_V_ALL0C_STACK_FIELD_2D 

fi ( signifjen, exp Jen) 

integer signifjen, exp Jen; 

FUNCTION INTEGER CMSR_V_ALLOC_STACK_FIELD_3D 

& ( signifjen, exp Jen) 

INTEGER signifjen, exp len; 

Lisp Syntax 

CMSR:v-alloc-stack-field-2d ( signif-len exp-len) 

CMSR: v-alloc-stack-field-3d ( signif-len exp-len) 
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CMSR_v_alloc_stack_field_2d 
CMSR_v_alloc_stack_field_3d 


ARGUMENTS 

signifjen The length, in bits, of the significand of the floating-point values 

to be stored in the returned field. 


exp Jen The length, in bits, of the exponent of the floating-point values to 

be stored in the returned field. 


DESCRIPTION 

CMSR_v_alloc_stack_field_2d and CMSR_v_alloc_stack_field_3d allo¬ 
cate a vector field on the stack and return its Paris field ID. 

A vector field is organized to contain an array of floating-point values. Each element of 
the vector has a length of {signifjen + exp Jen + 1), where signifjen is the length of 
the significand, exp Jen is the length of the exponent, and 1 is the sign bit. 

CMSR_v_alloc_stack_field_2d allocates a field organized as a 2-element array. 
The length of the entire field is 2 * {signifjen + exp Jen + 1). 

CMSR_v_alloc_stack_field_3d allocates a field organized as a 3-element array. 
The length of the entire field is 3 * {signifjen + exp Jen + 1). 

If the vector is a position vector, the field is organized so that x occupies the least signif¬ 
icant bits, y the following bits, and z the most significant bits. 


186 


Version 2.0, November 1991 



Chapter 3. Math Routines 


CMSR_v_copy_2d 

CMSR_v_copy_3d 


CMSR_v__copy_2d 

CMSR_v_copy_3d 

Copies the two (three)values in one vector field to another. 


SYNTAX 
C Syntax 

#include <cm/cznsr.h> 
void 

CMSR_v_copy_2d (destjvectorJield, src_vectorJield, signifjen, exp Jen) 

CM_field_id_t destvectorJield, src_yectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_copy_3d ( dest_vectorJield, src_yectorJield, signifjen, 
exp Jen) 

CM_field_id_t dest_vectorJield, src vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/indude/cm/cmsr-math-fort. h' 

SUBROUTINE CMSR_V_copy_2D 

& ( dest_vectorJield, src_vectorJield, signifjen, exp Jen) 

INTEGER dest_vectorJield, src_vectorJield 

INTEGER signifjen, exp len 


SUBROUTINE CMSR_V_copy_3D 

& (dest_vectorJield, src_vectorJield, signifjen, exp Jen) 

INTEGER dest_yectorJield, srcjyectorJield 

INTEGER signifjen, exp Jen 
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Lisp Syntax 

CMSR:v-copy-2d 

(dest-vector-field src-vector-field &optional signif-len exp-len) 

CMSR:v-copy-3d 

(dest-vector-field src-vector-field ^optional signif-len exp-len) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the vector field in CM memory 
to which srcjyector Jield is to be copied. 

src_yector Jield A Paris field identifier specifying the vector field in CM memory 

from which the vectors are to be copied. 

For CMSR_v_copy_2d this vector field contains two 
floating-point values, each having a length of (signiflen + 
exp Jen +1) bits. The vector field is organized so that x occupies 
the least significant bits and y the most significant bits. The length 
of the entire field is 2 * ( signiflen + exp Jen +1). 

For CMSR_v_copy_3d this vector field contains three 
floating-point values, each having a length of ( signif len + 
exp Jen + 1) bits. The vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * ( signif len + 
exp Jen + 1). 


signifjen The length, in bits, of the significand of the floating-point values 

in destvectorJield and src vector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vector Jield and srcjvector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_copy_2d and 
CMSR_v_copy_3d copy the value in src_vector Jield to dest vector Jield. 

All fields must be in the current VP set. dest_vectorJield may be file same field as 
srcjyector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_copy_const_2d 
CMS R_v_co py_co n s t_3 d 

Broadcasts a specified 2D (3D) vector to a vector field. 


Chapter 3. Math Routines 


SYNTAX 
C Syntax 

#indude <cm/cmsr.h> 
void 

CMSR_v_copy_const_2d (dest_vectorJield, srcvector, signifjen, 
exp len) 

CM_field_id_t dest_vectorJield; 
double src vector [ 2] ; 

unsigned int signifjen, exp len; 

void 

CMSR_v_copy_const_3d ( destvectorJield vector signifjen exp Jen) 

CM_field_id_t destvectorJield; 
double src_vector[ 3] ; 

unsigned int signifjen, exp len; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_COPY_CONST_2D 

& ( dest_vectorJield, src_yector, signifjen, exp Jen) 

INTEGER destjyectorJield 

DOUBLE PRECISION src_vector (2) 

INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_V_C0PY_C0NST_3D 

fi ( dest_vectorJield vector signifjen exp Jen) 

INTEGER dest_vectorJield 

DOUBLE PRECISION src_vector(3) 

INTEGER signifjen, exp Jen 
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CMSR_v_copy_const_2d 

CMSR_v_copy_const_3d 


Lisp Syntax 

CMSR : v-copy-cons t-2 d ( vector-field src-vector 

Soptional ( signif-len 23) ( exp-len 8)) 

CMSR:v-copy-const-3d ( vector-field src-vector 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destvectorJield A Paris field indentifier specifying the field in which the 2D vector 
is to be stored. Each element of the vector has a length of 
(signifjen + exp Jen + 1) bits. 

For CMSR_v_copy_const_2d the vector field contains two 
floating-point values organized so that x occupies the least 
significant bits and y the most significant bits. The length of the 
entire field is 2 * ( signifjen + exp Jen + 1). 

For CMSR_v_copy_const_3d the vector field contains three 
floating-point values organized so that x occupies the least 
significant bits, y the following bits, and z the most significant bits. 
The length of the entire field is 3 * ( signifjen + exp Jen +1). 

srcjvector A 1 x 2 array for CMSR_v_copy_const_2d or a 1 x 3 array for 

CMSR_v_copy_const_3d, containing the vector to be loaded 
into the vector field. 

signifjen The length, in bits, of the significand of the floating-point values 

in destvectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destvectorJield. 


DESCRIPTION 

For each active processor, CMSR_v_copy_const_2d and CMSR_v_copy_const_3d 
place the contents of srcvector in destvector Jield. 
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CMSR__v_copy_const_2d 

CMSR_v_copy_const_3d 


SEE ALSO 

CMSR_v_wri te_to_pr oce s sor__2 d 
CMSR_v_wri te__to__proces sor__3d 
CMSR_v_read_£ romjproces sor_2d 
CMSR_v_read_f romjproces s or_3d 
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CMS R_v__cos_betwee n_2d 
CMSR_v_cos_between_3d 

Finds the cosine of the angle between two 2D (3D) vectors. 


SYNTAX 
C Syntax 

#include <cm/cmsr. h> 
void 

CMSR_v_cos_between_2d 

(destJield, srcl vectorJield, src2_vectorJield, signifjen, exp Jen) 

CM_field_id_t destJield, srclvectorJield, src2_vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_cos_between_3d 

(destJield, srcl_yectorJeld, src2_yectorJeld, signifjen, exp Jen) 

CM_£ield_id_t destJeld, srcl_vectorJeld, src2_vectorJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_COS_BETWEEN_2D 

& (destJeld, srcl_vectorJeld, src2_vectorJeld, signifjen, exp Jen) 

INTEGER destJeld, srcljvectorJeld, src2_vectorJeld 

INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_V_COS_BETWEEN_3D 

& (destJeld, srcl_yectorJeld, src2_vectorJeld, signifjen, exp Jen) 

INTEGER destJeld, srcl_vectorJeld, src2_vectorJeld 

INTEGER signifjen, exp Jen 
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CMSR_v_cos_between_2d 

CMSR_v_cos_between_3d 


Lisp Syntax 

CMSR:v-cos-between-2d ( dest-field srcl-vector-field src2-vector-field 

&optional signif-len exp-len) 

CMSR:v-cos-between-3d ( dest-field srcl-vector-field src2-vector-field 

{■optional signif-len exp-len) 


ARGUMENTS 

destJield A Paris field identifier specifying the field in CM memory in 

which the cosine calculated by the routine is stored. The length of 
this field is ( signiflen + exp Jen +1) bits. 

srcl_vectorJield, src2_vectorJield 

Paris field identifiers specifying the vector field in CM memory 
containing the vectors to be operated on. 

For CMSR_v_cos_between_2d this vector field contains two 
floating¬ 
point values, each having a length of ( signiflen + exp Jen +1) 
bits. The vector field is organized so that x occupies the least 
significant bits and y the most significant bits. The length of the 
entire field is 2 * {signif len + exp len + 1). 

For CMSR_v_cos_between_3d this vector field contains three 
floating¬ 
point values, each having a length of {signiflen + exp Jen +1) 
bits. The vector field is organized so that x occupies the least 
significant bits, y the following bits, and z the most significant 
bits. The length of the entire field is 2 * {signif len + exp len + 
1 ) 

signifjen The length, in bits, of the significand of the floating-point values 

in the vector fields. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

the vector fields. 
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DESCRIPTION 

For each active processor in the current VP set, CMSR_y_cos_between_2d and 
CMSR_v_cos_between_3d find the cosine of the angle between the vectors in die two 
source fields and place the result in the destination field. This is the dot-product of the 
normalized vectors, however, the source field vectors need not be unit length. All 
fields must be in the current VP set. 

Note that the dest Jield is a standard floating-point field and not a vector. 
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CMSR_v_cross_product_3d 

Calculates the cross-product of two 3D vectors. 


SYNTAX 
C Syntax 


#include <cm/cmsr.h> 


void 

CMSR_v_cross_product_3d 

(i destvectorjeldsrcl vectorJield, src2_yectorJield, signifjen, exp len) 


CM_field_id_t 
CM_field_id_t 
CM_field_id_t 
unsigned int 


destvectorJield; 
srclvectorJield; 
src2vectorJield; 
signifjen, exp len; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_CR0SS_PR0DUCT_3D 

& (dest vectorJeld, srcl vectorJield, src2_vectorJield, signifjen, exp len) 

INTEGER destvectorJield 
INTEGER srcl_vectorJeld 
INTEGER src2_vectorJeld 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:v-cross-product-3d 

(i dest-vector-field srcl-vectorJeld src-vector-field-2 

fioptional ( signif-len 23 ) ( exp-len 8)) 


ARGUMENTS 

dest Jeld A Paris field identifier specifying the field in CM memory to 

which the result is written, dest Jeld must be in the same VP set 
as srcl_vector Jeld and src2_vector Jeld. 


Version 2.0, November 1991 


195 



*Render Reference Manual for Paris 


CMSR_v_cross_product_3d 


srcl_vectorJield, src2_vectorJield 

Paris field indentifiers specifying the fields in CM memory 
containing the 3D coordinates of the vectors. srcl_vectorJield 
and src2_vectorJield must be in the same VP set as destJield. 

The coordinates are floating-point values, each having a length of 
(signifjen + exp Jen +1) bits. The vector field is organized so 
that x occupies the least significant bits, y the following bits, and 
z the most significant bits. The length of the entire field is 3 * 
(signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in dest Jield, srcJieldJ, and srcJield_2. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest Jield, srcJieldJ, and srcJieldJ. 


DESCRIPTION 

For each active processor, CMSR_v_cross_product_3d calculates the cross-product 
between srcljyectorJield and src2_vectorJield and puts the result in the dest Jield. 

All fields must be in the current VP set. The dest field may be the same field as 
srcljyectorJield or src2j>ector Jield, or the fields may be totally disjoint. However, 
partially overlapping fields cause unpredictable results. 


SEE ALSO 

CMSR_fe_v_crossjproduct_3d 
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CMSR_v_dot_product_3d 

Calculates the dot product of two 2D (3D) vectors. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_do t_p r o du c t_2 d 

( productJeld, srcl vectorJield, src2vectorJield, signifjen, exp Jen) 

void 

CMSR_v_dot_product_3d 

(productJield, srcl_vectorJield, src2_vectorJeld, signiflen, exp Jen) 

CM_field_id_t productJield; 

CM_field_id_t srcl_vectorJeld; 

CM_field_id_t src2_vectorJeld; 
unsigned int signifjen; 
unsigned int exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_D0T_PR0DUCT_2D 

& (productJeld, srcl_yectorJeld, src2_vectorJeld, signifjen, exp Jen) 

SUBROUTINE CMSR_V_D0T_PR0DUCT_3D 

& (productJeld, srcl_yectorJeld, src2_vectorJeld, signifjen, exp len) 

INTEGER productJeld 
INTEGER srcl_yectorJeld 
INTEGER src2_vectorJeld 
INTEGER signifjen 
INTEGER exp Jen 


CMSR_v_dot_product_2d 

CMSR_v_dot_product_3d 
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Lisp Syntax 

CMSR: v-dot-product-2d (product-field src 1-vector-field src2-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR: v-dot-product-3d (product-field src 1-vector-field src2-vector-field 

fioptional ( signif-len 23) (exp-len 8)) 

ARGUMENTS 

product Jield A Paris field identifier specifying the field in CM memory to 

which the product of srcl_vectorJield and src2 vectorJield is 
written. 

srcl vectorJield, src2_vector Jield 

Paris field indentifiers specifying the fields in CM memory 
containing the vectors to be multiplied, srcl vector Jield and 
src2_vectorJield must be in the same VP set as product Jield. 

signifjen The length, in bits, of the significand of the floating-point values 

in product Jield, src Jield J, and src Jield_2. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

product Jield, src Jield_l, and src Jield_2. 


DESCRIPTION 

For each active processor, CMSR_v_dot_product_2d and CMSR_v_dot 
product_3d calculate the dot product of srcl ^vectorJield and src2_vectorJield and 
put the result in the product-field. 

For CMSR_v_dotjproduct_2d, productJield, srcl_vectorJield, and src2_vector_ 
field contain two floating-point values organized so that x occupies the least significant 
bits andy the most significant bits. Each element has a length of ( signifjen + exp Jen + 
1) bits where signifjen is the length of the significand, exp Jen is the length of the 
exponent, and 1 is the sign bit. The length of the entire field is 2 * {signifjen + exp Jen 
+ 1 ). 

For CMSR_v_dot_product_3d, product Jield, srcl_vector Jield, and src2_vector_ 
field contain three floating-point values organized so that x occupies the least signifi¬ 
cant bits, y the following bits, and z the most significant bits. Each element has a length 
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of ( signifjen + exp Jen +1) bits. The length of the entire field is 3 * ( signifjen + 
exp Jen +1). 

All fields must be in the current VP set. The product field may be the same field as 
srcl_vectorJield or src2_yectorJield, or the fields may be totally disjoint. However, 
partially overlapping fields cause unpredictable results. 


SEE ALSO 

CMSR_v_dot_jproduct_3d 
CMS R_f e_v_do t_jp r o du c t_2 d 
CMSR_fe_v_dot_product_3d 


Version 2.0, November 1991 


199 


CMSRjvJleldJength 


*Render Reference Manual for Paris 


CMSR_v_fieldJength 

Returns the length of a vector field of a specified rank. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
int 

CMSR_v_field_length (rank, signifjen, exp Jen); 
int rank ; 

unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 

integer FUNCTION CMSR_V_FIELD_LENGTH (rank, signifjen, expjen) 

integer rank 
INTEGER signifjen 
integer expjen 


Lisp Syntax 

CMSR:v-field-length (rank ^optional ( signif-len 23) (exp-len 8)) 


ARGUMENTS 

rank 


The number of dimensions in the vector for which the field is 
allocated. 


signifjen The length, in bits, of the significand of the floating-point values 

in the field. 

expjen The length, in bits, of the exponent of the floating-point values in 

the field. 


200 


Version 2.0; November 1991 





Chapter 3. Math Routines 


CMSR_v_field_length 


DESCRIPTION 

CMSR_v_field_length returns the length, in bits, of the Paris field that must be allo¬ 
cated to hold a vector of rank elements. 

Each element of the vector is assumed to be a floating-point value having a length of 
(signifjen + exp Jen +1), where signifjen is the length of the sigmficand, exp Jen is 
the length of the exponent, and 1 is the sign bit. 


SEE ALSO 

CMSR_m_field_length 
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CMSR_vJs_zero_2d 

CMSR_v_is_zero_3d 

Tests whether each 2D (3D) vector in a vector field is of length 0. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_is_zero_2d (bitJield, vectorJield, signifjen, exp Jen) 

CM_field_id_t bitJield, vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_is_zero_3d (bitJield, vectorJeld, signifjen, exp Jen) 

CM_field_id_t bitJeld, vectorJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_IS_ZERO_2D 

& (bitJeld, vectorJeld, signifjen, exp Jen) 

INTEGER bitJeld, vectorJeld; 

INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_V_IS_ZERO_3D 

& (bitJeld, vectorJeld, signifjen, exp Jen) 

INTEGER bitJeld, vectorJeld; 

INTEGER signifjen, exp Jen; 
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Lisp Syntax 

CMSR: v-is-zero-2d ( bit-field vector-field, 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR: v-is-zero-3d ( bit-field vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

bitJield 


vectorJield 


signifjen 


exp Jen 


A Paris field identifier specifying the field in CM memory in 
which the results of testing vector Jield are to be returned. 

A Paris field identifier specifying the field in CM memory 
containing the vectors to be tested. 

For the 2D routine these are 2-element arrays; for the 3D routine 
these are 3-element arrays. Each element is assumed to be a 
floating-point value having a length of ( signifjen + exp Jen + 1), 
where signifjen is the length of the significand, exp len is the 
length of the exponent, and 1 is the sign bit. 

The length, in bits, of the significand of the floating-point values 
in 

vectorJield. 

The length, in bits, of the exponent of the floating-point values in 
vector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_is_zero_2d and 
CMSR_v_is_zero_3d test whether the vector contained in vector Jield is zero length. 
If, in a particular processor, the vector in vector Jield is of length zero, the correspond¬ 
ing bit in bit Jield is set to 1. If the vector has non-zero length, the bit is set to 0. 
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CMSR__v_negate_2d 

CMSR_v_negate_3d 

Multiplies each vector element in the 2D (3D) vector field by -1. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_negate_2d 

( dest_vectorJield, src_vectorJield, signifjen, exp Jen) 

CM_field_id_t destvectorJield, src_vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_negate_3d 

(dest_vectorJield, src_yectorJield, signifjen, exp len) 

CM_field_id_t dest vectorJield, src vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_NEGATE_2D 

& ( dest_yectorJield, srcjvectorJield, signifjen, exp Jen) 

INTEGER dest_vectorJield, src_vectorJield 
INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_V_NEGATE_3D 

& ( dest_yectorJield, src_vectorJield, signifjen, exp Jen) 

INTEGER dest vector Jield, srcjvectorJield 
INTEGER signifjen, exp Jen 
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Lisp Syntax 

CMSR:v-negate-2d (dest-vector-field src-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR:v-negate-3d (dest-vector-field src-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 

ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the vector field in CM memory 

in which the inverted vectors are to be stored. 

src_vectorJield A Paris field identifier specifying the vector field in CM memory 

from which to read the vectors to be inverted. 

For CMSR_v_negate_2d this vector field contains two 
floating-point values, each having a length of ( signiflen + 
exp Jen +1) bits. The vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * (signif len + exp len + 1). 

For CMSR_v_negate_3d this vector field contains three 
floating-point values, each having a length of (signif len + 
exp Jen + 1) bits. The vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * (signif len + 
explen + 1). 

signif len The length, in bits, of the significand of the floating-point values 

in destjyector Jield and src_vector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjyector Jield and srcjyector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_negate_2d and 
CMSR_v_negate_3d multiply each vector element in src_vectorJield by -1 and put 
the result in dest_vectorJield. 
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CMSR_v_negate_2d 

CMSR_v_negate_3d 


Both fields must be in the current VP set. dest_vector Jield may be the same field as 
srcjvector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_normalize_2d 

CMSR_v_normalize_3d 

Normalizes each 2D (3D) vector in a vector field to a unit vector. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_normalize_2d 

(dest vectorJield, srcvectorJield, signifjen, expjen) 

CM_field__id_t destjyectorJield, src_vectorJield; 
unsigned int signif len, expjen; 

void 

CMSR_v_normalize_3d 

(dest_vectorJield, src_vectorJield, signif len, expjen) 

CM_field_id_t dest_vectorJield, src vectorJield; 
unsigned int signifjen, expjen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_N0RMALIZE_2D 

& ( dest_vectorJield, src_vectorJield, signifjen, expjen) 

INTEGER destjyectorJield, src_vectorJield 
INTEGER signifjen, expjen 

SUBROUTINE CMSR_V_NORMALIZE_3D 

& (dest vectorJield, src_yectorJield, signifjen, expjen) 

INTEGER dest_vectorJield, src_vectorJield 
INTEGER signifjen, expjen 
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Lisp Syntax 

CMSR:v-normalize-2d (dest-vector—field src-vector-field 

&optional ( signif-len 23) ( exp-len 8)) 

CMSR:v-normalize-3d (dest-vector—field src-vector-field 

&optional (signif-len 23) (exp-len 8)) 

ARGUMENTS 

dest_vector Jield A Paris field identifier specifying the vector field in CM memory 
in which the normalized vectors are to be stored. 

srcjyectorJield A Paris field identifier specifying the vector field in CM memory 

from which to read the vectors to be normalized. 

For CMSR_v_normalize_2d this vector field contains two 
floating-point values, each having a length of ( signifjen + 
exp Jen +1) bits. The vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * ( signifjen + exp Jen +1). 

For CMSR_v_normalize_3d this vector field contains three 
floating-point values, each having a length of (signifjen + 
exp Jen +1) bits. The vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * (signifjen + 
exp Jen +1). 

signifjen The length, in bits, of the significand of the floating-point values 

in dest_vectorJield and src_yectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vectorJield and srcjyectorJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_normalize_2d and 
CMSR_y_normalize_3d compute a unit vector pointing in the same direction as 
src vector Jield and puts the result in dest_vector Jield. 
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CMSR_v_normalize_2d 

CMSR_v_normalize_3d 


Both fields must be in the current VP set. dest_vector Jield may be the same field as 
srcjyector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_perpendicular_2d 

CMSR__v__perpendicular_3d 

Creates a unit vector perpendicular to one 2D vector (or two 3D vectors). 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_vjperpendicular_2d 

(dest vectorJield, srcjvectorJield, signifjen, exp Jen) 

CM_field_id_t dest_vectorJield, srcjvectorJield; 

unsigned int signifjen, exp Jen; 

void 

CMSR_v_perpendicular_3d 

(i dest_vectorJield, srcl vectorJield, src2_vectorJield, signifjen, 
exp Jen) 

CM_field_id_t destvectorJield, srcl vectorJield, src2_vectorJield; 

unsigned int signifjen, exp len; 


Fortran Syntax 

INCLUDE ' /usr/indude/cm/cmsr-math-fort. h' 

SUBROUTINE CMSR_V_PERPENDICUUVR_2D 

& (dest_yectorJield, src_yectorJield, signifjen, exp Jen) 

INTEGER dest_vectorJield, src_vectorJield 

INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_V_PERPENDICULAR_3D 

& (destvectorJield, srcl jvectorJield, src2_vectorJield, signifjen, exp Jen) 

INTEGER dest_vectorJield, srcl_vectorJield, src2_yectorJield 
INTEGER signifjen, exp Jen 
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CMSR_v_perpendicular_2d 

CMSR_v_perpendicular_3d 


mm 


Lisp Syntax 

CMSR:v-perpendicular-2d ( dest-vector-field src-vector-field 

Soptional ( signif-len 23) ( exp-len 8)) 

CMSR:v-perpendicular-3d 

(i dest-vector-field srcl-vector-field src2-vector-field 
^optional ( signif-len 23) (exp-len 8)) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the vector field in CM memory 
in which the results of the routine are stored. 

srcvectorJield, srcl_vectorJield src2 vectorJield 

Paris field identifiers specifying the vector field in CM memory 
containing the vectors to be operated on. 

For CMSR_v_perpendicular_2d, src vectorJield and 
dest_vectorJield contain two floating-point values, each having 
a length of (signiflen + exp Jen +1) bits. A 2D vector field is 
organized so that x occupies the least significant bits and y the 
most significant bits. The length of the entire field is 2 * 
(signiflen + exp Jen +1). 

For CMSR_y_perpendicular_3d dest_vectorJield, srcl_ 
vector_ field, and src2_vectorJield each contain three float¬ 
ing-point values, each having a length of (signiflen + exp Jen + 
1) bits. A 3D vector field is organized so that x occupies the least 
significant bits, y the following bits, and z the most significant 
bits. The length of the entire field is 2 * (signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in the vector fields. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

the vector fields. 
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DESCRIPTION 

For each active processor in the current VP set, CMSR_vjperpendicular_2d con¬ 
structs a unit vector perpendicular to src_vectorJield and puts the result in 
dest_yectorJield. The source vector need not be unit-length, but src-vector should not 
be zero length. 

For each active processor in the current VP set, CMSR_v_perpendicular_3d con¬ 
structs a unit vector perpendicular to srcl_vectorJield and src2_vectorJield and puts 
the result in dest_vector Jield. The source vectors need not be unit-length. 

All fields must be in the current VP set. dest_yector Jield may be the same field as 
src_vectorJield, srcl_vectorJield, or src2_vectorJield, or the fields may be totally 
disjoint. However, partially overlapping fields cause unpredictable results. 
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CMSR_v_print_2d 

CMSR_v_print_3d 

Prints on stdout the contents of a specified processor’s 2D (3D) vector field. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v__p r int_2d (processor, srcvectorJield, signifjen, exp Jen) 

void 

CMSR_v_print__3d (processor, srcjyectorJield, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t src_vectorJield; 
unsigned int signifjen ; 
unsigned int exp Jen ; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_PRINT_2D 

& (processor, src vectorJield, signifjen, exp Jen) 

SUBROUTINE CMSR__V_PRINT_3D 

& (processor, src_yectorJield, signifjen, exp Jen) 

INTEGER processor; 

INTEGER srcjyectorJield; 

INTEGER signifjen; 

INTEGER exp Jen; 

Lisp Syntax 

CMSR: v-print-2 d (processor src-vector Jield 

^optional (signif-len 23) (exp-len 8)) 

CMSR: v-print-3d (processor src-vector Jield 

fioptional (signif-len 23) (exp-len 8)) 
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CMSR_v_print_2d 

CMSR_v_print_3d 


ARGUMENTS 

processor The send address of the processor from which you wish to print 

the vector. 

src_vector Jield Paris field identifiers specifying the vector field in CM memory 

containing the vector to be printed. 

For CMSR_v_print_2d the vector field contains two 
floating-point values, each having a length of {signifjen + 
exp Jen +1) bits. The vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * ( signifjen + exp Jen + 1). 

For CMSR_v_print_3d the vector field contains three 
floating-point values, each having a length of ( signifjen + 
exp Jen +1) bits. The vector field is organized so that jc occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * ( signifjen + 
exp len + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in the vector fields. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

the vector fields. 


DESCRIPTION 

CMSR_v_print_2d and CMSR_vjprint_3d print on stdout the double-precision 
floating-point contents of src vector Jield in the given processor. 

The vector elements are printed on a single line, separated by spaces, and followed by a 
carriage return. 
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CMSR_v_read_from_processor_3d 

Reads a 2D (3D) vector field from a specified processor into a front-end array. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
double * 

CMSR_v_read_from_processor_2d 

( processor, src_vectorJield, dest_vector, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t src_yectorJield; 
double dest_vector[2]; 

unsigned int signifjen, exp Jen; 

double * 

CMS R_v_r e a a_f r om_p rocessor_3d 

( processor, src vectorJield, dest_vector, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t src_vectorJeld; 
double dest vector [ 3 ] ; 

unsigned int signifjen, exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_READ_FROM_PROCESSOR_2D 

& (processor, src_vectorJield, destjvector, signifjen, exp Jen) 

INTEGER processor 

INTEGER src_vectorJeld 

DOUBLE PRECISION dest_vector(2) 

INTEGER signifjen, exp Jen 
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SUBROUTINE CMSR_V_READ_FROM_PROCESSOR_3D 

& {processor, srcjvectorJield, dest_vector, signifjen, exp Jen) 

INTEGER processor 

INTEGER src_vectorJield 

DOUBLE PRECISION dest_vector{3) 

INTEGER signifjen, exp Jen 

Lisp Syntax 

CMSR:v-read-from—processor-2d 

{processor vector-field 

&optional dest-vector {signif-len 23) (exp-len 8) ) 

CMSR:v-read-from-processor-3d 

(processor vector-field 

fioptional dest-vector (signif-len 23) (exp-len 8)) 


ARGUMENTS 

processor The processor send address from which the vector is to be read. 

srcjvector Jield A Paris field ^identifier specifying the field in processor from 

which the 2D vector is to be read. Each element of the vector has 
a length of (signifjen + exp Jen + 1) bits. 

A 2D vector field contains two floating-point values organized so 
that x occupies the least significant bits and y the most significant 
bits. The length of the entire field is 2 * (signifjen + exp Jen + 1). 

A 3D vector field contains three floating-point values organized so 
that jc occupies the least significant bits, y the following bits, and 
z the most significant bits. The length of the entire field is 3 * 
(signifjen + exp Jen +1). 

dest_vector For CMSR_y_read_from_processor_2d a 1 x 2 array, or for 

CMSR_v_read_f romjprocessor_3d a 1 x 3 array, in which the 
vector is to be returned. 

signifjen The length, in bits, of the significand of the floating-point values 

in srcjvectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

src_vectorJeld. 
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CMSR_v_read_from_processor_3d 


DESCRIPTION 

CMSR_v_read_from_processor_2d and CMSR_y_read_from_processor_3d 

read and return the contents of vector Jield from the given processor, processor, to 
destvector. 

In C and Lisp these routines also return a pointer to destvector. 

If the dest vector parameter on the front-end is NULL, a new vector is allocated. 


SEE ALSO 

CMSR_v_write_to_processor_2d 
CMSR_v_write_to_processor_3d 
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CMSR_v_reflect_2d 

CMSRjvj-eflect_3d 

Calculates a 2D (3D) reflectance vector for specified incident and normal vectors. 


SYNTAX 

C Syntax 

tinclude <cm/cmsr.h> 
void 

CMS R_v_re flee t_2 d 

(dest vectorJield, srcjyectorJield, normaljvectorJield, 
signifjen, exp len) 

CM_field_id_t dest_vectorJield, src_yectorJield, normal vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_reflect_3d 

(dest vectorJield, src_vectorJield, normal_yectorJeld, 
signifjen, exp Jen) 

CM_fie 1 d_id_t dest_vectorJeld, src_yectorJeld, normal_vectorJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/emsr-math-fort.h' 

SUBROUTINE CMSR_V_REFLECT_2D 

& ( destjyectorJeld, src_vectorJeld, normal vectorJeld, 

& signifjen, exp Jen) 

INTEGER dest_yectorJeld, src_vectorJeld, normalyectorJeld 
INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_V_REFLECT_3D 

& ( dest_vectorJeld, srcjvectorJeld, normal_vectorJeld, 

& signifjen, exp Jen) 

INTEGER dest_vectorJeld, src_vectorJeld, normal vectorJeld 
INTEGER signifjen, exp Jen 
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CMSR_v_reflect_2d 

CMSR_v_reflect_3d 


Lisp Syntax 

CMSR:v-reflect-2d 

(dest-vector-field src-vector-field normal-vector-field 
Soptional (signif-len 23) (exp-len 8)) 

CMSR:v-reflect-3d 

(dest-vector-field src-vector-field normal-vector-field 
&optional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

dest vector Jield A Paris field identifier specifying the vector field in CM memory 
in which the reflectance vector is stored. 

src vector Jield A Paris field identifier specifying the vector field in CM memory 

containing the vector indicating the direction of the incident light. 

normalvectorJield 

A Paris field identifier specifying the vector field in CM memory 
containing the vector indicating the surface normal of the surface 
from which the light is to reflect. 

For CMSR_v_reflect_2d this vector field contains two 
floating-point values, each having a length of (signifjen + 
exp Jen + 1) bits. A 2D vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * {signiflen + exp Jen + 1). 

For CMSR_v_reflect_3d this vector field contains three 
floating-point values, each having a length of ( signifjen + 
exp Jen +1) bits. A 3D vector field is organized so that jc occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * ( signifjen + 
exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in dest_vector Jield, src_vector Jield, and normal vector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vector Jield, src_vector Jield, and normal_vector Jield. 
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CMSR_v_refleet_2d 

CMSR_v_refleet_3d 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_reflect_2d and 
CMSR_v_reflect_3d determine the vector resulting from reflecting src_vector Jield 
around normal_vector Jield and put the result in dest_vectorJield. The vectors in 
src_vectorJield and normal_vectorJield need not be unit-length, but the reflected 
vectors in dest_vector Jield will be. 

All fields must be in the current VP set. destjyector Jield may be the same field as 
src_vector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 

To build the destination vector in each processor, the incident and normal vectors are 
first normalized. The reflected vector (R), is then constructed from the unit-length inci¬ 
dent vector (I) and unit-length normal vectors (N) ; 

R = I-2*(N dot I)*N 


normal vector (N) 
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CMSR_v_ref_x 

CMSR_v_ref_y 

CMSR_v_ref_z 

Returns the field ID of an element of a 2D (3D) vector. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 

CM_field_id_t 

CMSR_v_ref_x ( vectorJield, signifjen, exp Jen) 

CM_field_id_t 

CMSR_v_ref_y ( vectorJield, signifjen, exp Jen) 

CM_field_id_t 

CMSR_v_ref_z (vectorJield, signifjen, exp len) 

CM_field_id_t vectorJield; 
unsigned int signifjen; 
unsigned int exp Jen; 

Fortran Syntax 

INTEGER FUNCTION CMSR_V_REF_X (vectorJield, signifjen, exp Jen) 

INTEGER FUNCTION CMSR_V_REF_Y (vectorJield, signifjen, exp Jen) 

INTEGER FUNCTION CMSR_V_REF_Z (vectorJield, signifjen, exp Jen) 

INTEGER vectorJield 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR:v-ref-x (vector-field fioptional (signif-len 23) (exp-len 8)) 

CMSR:v-ref-y (vector-field &optional (signif-len 23) (exp-len 8)) 

CMSR:v-ref-z (vector-field fioptional (signif-len 23) (exp-len 8)) 
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ARGUMENTS 

vector Jield The Paris field ID of the vector from which the element is to be 

read. 

signifjen The length, in bits, of the significand of the floating-point values 

in the field. 


exp Jen The length, in bits, of the exponent of the floating-point values in 

the field. 


DESCRIPTION 

CMSR_v_ref_x, CMSR_v_ref_y and CMSR_v_ref_z return the field ID of the sub¬ 
field of vector Jield containing, respectively, the x, y, or z element of the vector. 

The length of each element is ( signifjen + exp Jen +1) bits, where signifjen is the 
length of the coordinate significand, exp Jen is the length of the coordinate exponent, 
and 1 is the sign bit. The vector field is organized so that x occupies the least significant 
bits, y the following bits, and z the most significant bits. 
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CMSR_v_scale_2d 

CMSR_v_scale_3d 

Multiplies a 2D (3D) vector field by a scaling factor field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_scale_2d 

( destvectorJield, src_vectorJield, scaleJield, signifjen, exp Jen) 

CM_field_id_t dest_vectorJield, src_vectorJield, scaleJield; 
unsigned int signifjen, exp Jen; 

void 

CMS R_v_s c a1 e_3d 

(i destjyectorJeld, src_vectorJeld, scaleJeld, signifjen, exp Jen) 

CM_field_id_t dest_vectorJeld, src_vectorJeld, scaleJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_SCALE_2D 

& (dest_yectorJeld, src_vectorJeld, scaleJeld, signifjen, exp Jen) 

INTEGER dest_vector Jeld, src_vector Jeld, scale Jeld; 

INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_V_SCALE_3D 

& ( dest_vectorJeld, src_vectorJeld, scaleJeld, signifjen, exp Jen) 

INTEGER dest_vectorJeld, srcjyectorJeld, scaleJeld; 

INTEGER signifjen, exp Jen; 
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CMSR_v_scale_2d 

CMSR_v_scale_3d 


Lisp Syntax 

CMSR : v-scale-2d ( dest-vector-field src-vector-field scale-field 
^optional ( signif-len 23) ( exp-len 8)) 

CMSR : v-scale-3d ( dest-vector-field src-vector-field 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjyector Jield A Paris field identifier specifying the vector field in CM memory 
in which the scaled vectors are to be stored. 

src_vectorJield A Paris field identifier specifying the vector field in CM memory 

in which the vectors to be scaled are stored. 

For CMSR_v_scale_2d this vector field contains two 
floating-point values, each having a length of ( signiflen + 
exp Jen + 1) bits. A 2D vector field is organized so that jc occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * ( signiflen + exp Jen +1). 

For CMSR_v_scale_3d this vector field contains three 
floating-point values, each having a length of ( signif len + 
exp len + 1) bits. A 3D vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * {signif len + 
exp Jen + 1). 

scale Jield A Paris field identifier specifying the factors by which the vectors 

in src_vector Jield are to be scaled. 

signifjen The length, in bits, of the significand of the floating-point values 

in dest_vector Jield and src_vector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vector Jield and src_vector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_scale_2d and 
CMSR_v_scale_3d multiply each component of src_vectorJield by scaleJield, and 
place the result in dest_vector Jield. 
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CMSR_v_scale_2d 

CMSR_v_scale_3d 


All fields must be in the current VP set. dest_vector Jield may be the same field as 
src_vector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_scale_const_2d 

CMSR_v_scale_const_3d 

Multiplies a 2D (3D) vector field by a scaling factor constant. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_scale_const_2d 

(dest_vectorJield, srcvectorJield, scale, signifjen, exp Jen) 

CM_field_id_t destvectorJield, srcjyectorJield; 

double scale; 

unsigned int signifjen, exp Jen; 

void 

CMSR_v_scale_const_3d 

( dest_yectorJield, srcvectorJield, scale, signifjen, exp Jen) 

CM_field_id_t dest vectorJield, srcjvectorJield; 

double scale; 

unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_SCALE_CONST_2D 

& (dest_vectorJield, src_vectorJield, scale, signifjen, exp Jen) 

INTEGER dest_vectorJield, src_vectorJield; 

DOUBLE PRECISION scale; 

INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_V_SCALE_CONST_3D 

& (destvectorJield, src_vectorJield, scale, signifjen, exp Jen) 

INTEGER dest vectorJield, src_vectorJield; 

DOUBLE PRECISION scale; 

integer signifjen, exp Jen; 
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CMSR_v_scale_const_2d 

CMSR_v_scale_const_3d 


Lisp Syntax 

CMSR:v-scale-const-2d ( dest-vector-field src-vector-field scale 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR:v-scale-const-3d ( dest-vector-field src-vector-field scale 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

dest vectorJield A Paris field identifier specifying the vector field in CM memory 

in which the scaled vectors are to be stored. 

src_vector Jield A Paris field identifier specifying the vector field in CM memory 

in which the vectors to be scaled are stored. 

For CMSR_v_scale_const_2d this vector field contains two 
floating-point values, each having a length of {signiflen + 
exp Jen +1) bits. A 2D vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * ( signif len + exp len + 1). 

For CMSR_v_scale_const_3d this vector field contains three 
floating-point values, each having a length of ( signif len + 
exp Jen + 1) bits. A 3D vector field is organized so that jc occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * ( signif len + 
exp Jen +1). 

scale The factor by which the vectors in src_vector Jield are to be 

stored. 

signifjen The length, in bits, of the significand of the floating-point values 

in destjyectorJield and src vector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vectorJield and src_vectorJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR__v_scale_const_2d and 
CMSR_v_scale_const_3d multiply each component of srcjyectorJield by the con¬ 
stant value scale, and place the result in dest_vectorJield. 
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Both fields must be in the current VP set. dest_vector Jield may be the same field as 
src_vector Jield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_subtract_3d 


CMSR_v_subtract_2d 
C MS R_v_s u btract_3d 

Subtracts one 2D (3D) vector from another. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_subtract_2d 

( destvectorJield, srcl _vectorJield, src2_vectorJield, signifjen, exp Jen) 

CM_field_id_t dest_vectorJield, srcl_yectorJield, src2_vectorJield-, 
unsigned int signifjen, exp Jen; 

void 

CMSR_v_subtract_3d 

{dest_yectorJeld, srcl_vectorJeld, src2_vectorJeld, signif len, exp len) 

CM_field_id_t dest_vectorJeld, srcl_vectorJeld, src2_vectorJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_SUBTRACT_2D 

& ( dest_vectorJeld, srcl _yectorJeld, src2_vectorJeld, signifjen, exp Jen) 

INTEGER dest_vectorJeld, srcl_vectorJeld, src2_vectorJeld 
integer signifjen, exp Jen 

SUBROUTINE CMSR_V_SUBTRACT_3D 

& (destvectorJeld, srcl_vectorJeld, src2_vectorJeld, signifjen, exp Jen) 

INTEGER dest_vectorJeld, srcl_vectorJeld, src2_vectorJeld 
INTEGER signifjen, exp Jen 
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Lisp Syntax 

CMSR: v-subtract-2d (dest-vector-field srcl-vector-field src2-vector-field 

Soptional ( signif-len 23) (exp-len 8)) 

CMSR:v-subtract-3d (dest-vector-field srcl-vector-field src2-vector-field 

Soptional ( signif-len 23) (exp-len 8)) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the vector field in CM memory 
in which the results of the subtraction are to be stored. 

srclvectorJield, src2_vector Jield, 

Paris field identifiers specifying the vector field in CM memory in 
which the vectors to be subtracted are stored. 

For CMSR_v_subtract_2d this vector field contains two 
floating-point values, each having a length of (signifjen + 
exp Jen + 1) bits. A 2D vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * (signifjen + exp Jen +1). 

For CMSR_v_subtract_3d this vector field contains three 
floating-point values, each having a length of (signif jen + 
exp Jen +1) bits. A 3D vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * (signifjen + 
exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in destvectorJield and src_vectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

dest_vectorJield and src_vectorJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_subtract_2d and 
CMSR_y_subtract_3d subtract each element of src2_vectorJield from srcl Rec¬ 
torJield (srcl_vectorJield - src2_yectorJield) and put the result in dest_vector. 
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CMSR_v_subtract_2d 

CMSR_v_subtract_3d 


Both fields must be in the current VP set. dest_yector Jield may be the same field as 
src_vectorJield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 
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CMSR_v_transform_2d 
CMS R_v__t ra n sfo rm_3d 

Applies a 2D (3D) transformation matrix field to a vector field. 

SYNTAX 
C Syntax 

#indude <cm/cmsr. h> 
void 

CMSR__v_trans f orm_2d 

(destjvectorJield, src vectorJield, srcjnatrixJield, signifjen, exp len) 
void 

CMSR_v_tran s f orm_3 d 

(dest_vectorJield, src_yectorJield, srcjnatrixJield, signiflen, exp Jen) 

CM_field_id_t dest_yectorJield; 

CM_field_id_t srcvectorJield; 

CM_field_id_t srcjnatrixJield; 
unsigned int signifjen; 
unsigned int exp Jen; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_TRANSFORM_2d 

& ( dest_vectorJield, srcjvectorJield, srcjnatrixJield, signifjen, exp Jen) 

SUBROUTINE CMSR_V_TRANSFORM_3d 

& (destvectorJield, srcj/ectorJield, srcjnatrixJield, signifjen, exp Jen) 

INTEGER destj/ectorJield 

INTEGER srcj>ectorJield 

INTEGER srcjnatrixJield 

INTEGER signifjen 

INTEGER exp Jen 
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CMSR_v_transform_2d 

CMSR_v_transform_3d 


Lisp Syntax 

CMSR:v-transformed ( dest-vector-field src-vector-field src-matrix-field 

Soptional ( signif-len 23) (exp-len 8)) 

CMSR: v-transformed ( dest-vector-field src-vector-field matrix-field 

&optional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the field in CM memory to 
which the transformed vector is written. dest_vectorJield must be 
in the same VP set as srcjvectorJield and srcjnatrixJield. 

src_vectorJield A Paris field identifier specifying the field in CM memory from 

which the vector to be transformed is taken, src vector Jield must 
be in the same VP set as destjyector Jield and srcmatrixJield. 

The vector elements are floating-point values each having a length 
of ( signifjen + exp Jen +1) bits, where signifjen is the length of 
the significand, exp Jen is the length of the exponent, and 1 is the 
sign bit. 

For CMSR_v_transform_2d the vector field is organized so that 
x occupies the least significant bits and y the most significant bits. 
The length of the entire field is 2 * {signifjen + exp Jen +1). 

For CMSR_v_transform_3d the vector field is organized so that 
x occupies the least significant bits, y the following bits, and z the 
most significant bits. The length of the entire field is 3 * 
{signifjen + exp Jen + 1). 

srcjnatrixJield A Paris field identifier specifying the field in CM memory 

containing the homogeneous transformation matrix to be applied 
to the source vector, srcjnatrix Jield must be in the same VP set 
as src_vector Jield and destj>ector Jield. 

Each element of the matrix is a floating-point value having a 
length of {signifjen + exp Jen +1), where signifjen is the length 
of the significand, exp Jen is the length of the exponent, and 1 is 
the sign bit. 

For CMSR_v_transform_2d the matrix field contains a 3 x 3 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 9 * {signifjen + exp Jen + 1). 
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For CMSR_v_transform_3d the matrix field contains a 4 x 4 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 16 * ( signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in src_vectorJield, dest_vectorJield, and src_matrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

srcjectorJield, dest_yectorJield, and srcjnatrix Jield. 


DESCRIPTION 

For each active processor, CMSR_v_transform_2d and CMSR_v_transform_3d 
apply the transformation defined by the matrix in srcjnatrix Jield to the vector in 
src_yectorJield and write the transformed vector into dest_vectorJield. 

Note that the matrix is a homogeneous transformation, (3x3 for 2D and 4 x 4 for 3D), 
but the vectors do not support homogeneous coordinates. That is, the 2D vector has 
only two elements ([xy] instead of [xyw]), and the 3D vector has only 3 elements ([xyz] 
instead of [xyzw]). This means that the resulting vector is actually of the form x/w,y/w, 
and, if 3D z/w. 

All fields must be in the current VP set. The destjector Jield may be the same field as 
src_vectorJield, or the two fields may be totally disjoint. However, partially overlap¬ 
ping fields cause unpredictable results. 


SEE ALSO 

CMSR_v_transform_const_2d 
CMSR_v_transform_const_3d 
CMSR_fe__y_trans f orm_2d 
CMSR fe v transform 3d 
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CMSR_v_transform_const_2d 

CMSR_v_transform_const_3d 

Applies a single 2D (3D) transformation matrix to a 2D vector field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_v_trans f orm_cons t_2d 

(i dest_vectorJield, src_vectorJield, srcjnatrix, signifjen, exp Jen) 

CM_field_id_t dest_vectorJield; 

CM_field_id_t srcvectorJield; 
double srcjnatrix [ 3 ] [3]; 

unsigned int signifjen, exp Jen; 

void 

CMSR_v_transform_const_3d 

(dest_vectorJield, src_vectorJeld, srcjnatrix, signifjen, exp Jen) 

CM_field_id_t dest_vectorJeld; 

CM_f i e 1 d_i d_t srcvectorJeld; 
double srcjnatrix[ 4] [4]; 

unsigned int signifjen, exp len; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_TRANSFORM_CONST_2D 

& ( dest_vectorJeld, src_vectorJeld, srcjnatrix, signifjen, exp Jen) 

INTEGER dest_vectorJeld 

INTEGER src_vectorJeld 

DOUBLE PRECISION srcjnatrix (3 , 3) 

INTEGER signifjen 

INTEGER exp Jen 

SUBROUTINE CMSR_V_TRANSF0RM_C0NST_3D 
& ( dest_vectorJeld, srcvectorJeld, srcjnatrix, signifjen, exp Jen) 
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INTEGER 

INTEGER 

DOUBLE PRECISION 

INTEGER 

INTEGER 


dest_vectorJield 
src_vectorJield 
src_matrix(l ,4) 
signifjen 
exp Jen 


Lisp Syntax 

CMSR:v-transform-const-2d 

( dest-vectorJield src-vector-field src-matrix 

{■optional ( signif-len 23) ( exp-len 8)) 

CMSR:v-transform-const-3d 

( dest-vector Jield src-vectorjield src-matrix 
fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

dest_vectorJield A Paris field identifier specifying the field in CM memory to 
which the transformed vector is written, dest vector Jield must be 
in the same VP set as src_vector Jield. 

src_yector Jield A Paris field identifier specifying the field in CM memory from 

which the vector to be transformed is taken. src_yector Jield must 
be in the same VP set as dest_vector Jeld. 

The vector elements are floating-point values each having a length 
of ( signifjen + exp Jen + 1) bits, where signifjen is the length of 
the significand, exp Jen is the length of the exponent, and 1 is the 
sign bit. 

For CMSR_v_transform_const_2d the vector field is 
organized so that x occupies the least significant bits and y the 
most significant bits. The length of the entire field is 2 * 

(signifjen + exp Jen + 1). 

For CMSR_v_transform_const_3d the vector field is 
organized so that x occupies the least significant bits, y the 
following bits, and z the most significant bits. The length of the 
entire field is 3 * ( signifjen + exp Jen + 1). 

srcjnatrix For CMSR_v_transf orm_cons t_2d a 3 x 3 homogeneous trans¬ 

formation matrix, or for CMSR v transform const 3d a 4x4 
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CMSR_v_transform_const_2d 

CMSR_v_transform_const_3d 


signiflen 
exp Jen 


DESCRIPTION 

CMSR_v_transform_const_2d applies the transformation defined by srcjnatrix to 
the vector in src_vector Jield in each active processor and writes the transformed vec¬ 
tor into dest_vectorJield. 

Note that the matrix is a homogeneous transformation, (3x3 for 2D and 4 x 4 for 3D), 
but the vectors do not support homogeneous coordinates. That is, the 2D vector has 
only two elements ([xy] instead of [xyw]), and the 3D vector has only 3 elements ([xyz] 
instead of [xyzw]). This means that the resulting vector is actually of the form x/w, y/w, 
and, if 3D z/w. 

All fields must be in the current VP set. The dest vector Jield may be the same field as 
src_vectorJield, or the two fields may be totally disjoint. However, partially overlap¬ 
ping fields cause unpredictable results. 


matrix, stored on the front-end computer in row-major order. Each 
element of the matrix is a double-precision floating-point value. 

The length, in bits, of the significand of the floating-point values 
in src_vector Jield, and dest_yector Jield. 

The length, in bits, of the exponent of the floating-point values in 
src_vectorJield, and dest_vectorJeld. 


SEE ALSO 

CMSR_v_transform_2d 
CMSR_v_transform_3d 
CMSR_fe_v_transform_2d 
CMSR fe v transform 3d 
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CMSR_v_transmlt_3d 


CMSR_v_transmit_3d 

Creates a transmittance vector for light refracted through two materials. 


SYNTAX 
C Syntax 


#include <cm/cmsr.h> 
void 

CMSR_v_transxnit_3d 

{transmitted vectorJield, incident_vectorJeld, normal_vectorJield, 
index 1, index2, signifjen, exp Jen) 

CM_field_id_t transmitted vectorJield, incident vectorJield; 
CM_field_id_t normal_yectorJield; 

CM_field_id_t indexl, index2; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_TRANSMIT_3D 

& {transmitted_yectorJield, incident vector Jeld, normaljyector Jield, 

& indexl, index2, signifjen, exp Jen) 

INTEGER transmitted_vectorJeld, incident_yectorJeld, normal_vectorJeld 
INTEGER indexl, index2 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:v-transmit-3d 

{transmitted-vector-field incident-vector-field normal-vector-field 
indexl index2 ^optional {signif-len 23) {exp-len 8)) 
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CMSR_v_transmit_3d 


ARGUMENTS 

transmittedvectorJield 

A Paris field identifier specifying the vector field in CM memory 
in which vectors indicating the direction of the transmitted light is 
stored. 

incidentvectorJield 

A Paris field identifier specifying the vector field in CM memory 
containing the vectors indicating the direction of the incident 
light. 

normal_yectorJield 

A Paris field identifier specifying the vector field in CM memory 
containing the vectors indicating the surface normal of the surface 
through which the light is to pass. 

For CMSR_v_transmit_2d this vector field contains two 
floating-point values, each having a length of ( signifjen + 
exp Jen +1) bits. A 2D vector field is organized so that x occupies 
the least significant bits andy the most significant bits. The length 
of the entire field is 2 * (signiflen + exp Jen + 1). 

For CMSR_v_transmit_3d this vector field contains three 
floating-point values, each having a length of (signif len + 
exp Jen + 1) bits. A 3D vector field is organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 2 * (signifjen + 
exp Jen + 1). 

indexl, index2 The index of refraction of the medium containing incident_vector 
and transmittedvector, respectively. 

signifjen The length, in bits, of the significand of the floating-point values 

in transmitted vector Jield, incident vector Jeld, and normal_ 
vectorJeld. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

transmitted vector Jeld, incident vector Jeld, and normal_ 
vectorJeld. 
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CMSR_v_transmit_3d 


DESCRIPTION 

For each active processor in the current VP set, CMSR_v_transmit_2d and 
CMSR_v_transmit_3d calculate the vector of the transmitted light based on the inci¬ 
dent _yectorJield, normalvectorJield, and indices of refraction for the two materials, 
indexl, and index2. The result of this calculation in each processor is stored in the 
transmitted vector Jield. All fields must be in the current VP set. 

The unit length transmitted vector T is given by: 

T = (nl/n2)*I+((nl/n2)*(N dot -I)-sqrt(l+(nl/n2) A 2*((N dot -I) A 2)-1))*N 

N is the unit vector in the direction of normalfvector. I is the unit vector in the direction 
of incident_vector. nl is indexl , the index of refraction of the medium containing the 
incident vector. n2 is index2, the index of refraction of the medium which contains the 
transmitted vector. 


normalvector (N) 


incidentvector (I) 




incident medium 


\ 


lliftransmittance medium 
transmitted_vector (T) 


If the expression under the square root becomes negative, the result is total internal 
reflection. If total internal reflection occurs, CMSR_y_transmit_3d returns a NULL 
pointer. 

Neither the incident vector nor the normal vector should be length 0. The second index 
of refraction should not be 0. 
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CMSR_v_write_to_processor_2d 

CMSR_v_write_to_processor_3d 

Writes a 2D (3D) vector from a front-end array into a specified processor’s vector field. 


SYNTAX 
C Syntax 

#indude <cm/cmsr.h> 
void 

CMSR_v_write_to_processor_2d 

( processor, dest_yector_field, src_vector, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t dest_yectorJield; 
double src_vector[ 2] ; 

unsigned int signifjen, exp Jen; 

void 

CMSR_v_write_to_processor_3d 

( processor, destvectorJield, srcvector, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t dest_vectorJield; 
double src_vector[ 3] ; 

unsigned int signifjen, exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_V_WRITE_TO_PROCESS0R_2D 

& (processor, dest_vectorJield, src_yector, signifjen, exp Jen) 

INTEGER processor 

INTEGER dest_vectorJield 

DOUBLE PRECISION src_vector( 2) 

INTEGER signifjen, exp-len 
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CMS R_v_write_to_p ro c ess o r_2 d 
CMSR_v_write_to_processor_3d 


SUBROUTINE CMSR_V_WRITE_TO_PROCESSOR_3D 

& ( processor, destvectorJield, srcjyector, signifjen, exp Jen) 

INTEGER processor 

INTEGER destyyectorJield 

DOUBLE PRECISION src_vector( 3) 

INTEGER signiflen 

INTEGER exp-len 

Lisp Syntax 

CMSR:v-write-to-processor-2d 

(processor vector-field src-vector 
^optional ( signif-len 23) ( exp-len 8)) 

CMSR:v-write-to-processor-3d 

(processor vector-field src-vector 
^optional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

processor The processor send address to which the vector is to be sent. 

dest_vector Jield A Paris field indentifier specifying the field in processor in which 
the 2D vector is to be stored. Each element has a length of 
(signifjen + exp Jen +1) bits. 

For CMSR_v-write-to-processor-2d the vector field 
contains two floating-point values organized so that x occupies the 
least significant bits andy the most significant bits. The length of 
the entire field is 2 * ( signifjen + exp len +1). 

For CMSR_v__write_to_processor_3d the vector field 
contains three floating-point values organized so that x occupies 
the least significant bits, y the following bits, and z the most 
significant bits. The length of the entire field is 3 * ( signifjen + 
exp Jen +1). 

src_vector For CMSR_v-write-to-processor-2d a 1 x 2 array, or for 

CMSR_v_write_to_j?rocessor_3d a 1 x 3 array, containing 
the vector to be loaded into the vector field. 

signifjen The length, in bits, of the significand of the floating-point values 

in dest_vector Jield. 
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CMSR_v_write_to_processor_2d 

CMSR_v_write_to_processor_3d 


exp_len The length, in bits, of the exponent of the floating-point values in 

dest_vectorJield. 


DESCRIPTION 

CMSR_v-write-to-processor-2d and CMSR_v_write_to_processor_3d 

place the contents of src_vector in dest_vectorJield in processor. 


SEE ALSO 

CMSR_v_read_from_processor_2d 

CMSR_v_read_from_processor_3d 
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3.7 CM Matrix Routines 

This section documents the *Render routines that operate on matrices in Paris fields in CM 
memory. Matrices in *Render are assumed to be square, homogeneous matrices. ’•‘Render 
supports matrices of dimension 2 or 3, for transforming two-dimensional or three-dimen¬ 
sional vectors. 

On the CM, a matrix is a field of (dimension + 1) * (dimension + 1 ){signif_len + exp Jen 
+1) bits, where signifjen is the length of the significand, exp Jen is the length of the expo¬ 
nent, and the 1 is for a sign bit. Each matrix element occupies one floating-point field of 


(signifjen + exp Jen +1) bits. 

The routines documented here are: 

CMSR_identity_matrix_2d. 246 

CMSR_identity_inatrix_3d. 246 

CMSR_m_alloc_heap_field_2d . 248 

CMSR_m_alloc_heap_field_3d . 248 

CMSR_m_alloc_stack_£ield_2d . 250 

CMSR_m_alloc_stack_field_3d . 250 

CMSR_m_copy_2d. 252 

CMSR_m_copy_3d. 252 

CMSR_m_copy_const_2d. 254 

CMSR_m_copy_const_3d. 254 

CMSR_m_determinant_2d . 256 

C3fSR_m_determlnant_3d . 256 

CMSR_m_field_length. 258 

CMSR_m_invert_2d. 260 

CMSR_m_invert_3d. 260 

CMSR_m_imiltiply_2d. 262 

CMSR_m_multiply_3d . 262 

CMSR_m_multiply_const_2d. 265 

CMSR_m_niultiply_const_3d. 265 

CMSR_m_p r int_2d. 268 


244 


Version 2.0, November 1991 























Chapter 3. Math Routines 

CMSRjajprint_3d . 268 

CMSR_m_read_from_processor_2d. 270 

C^R_m_read_from_processor_3d. 270 

CMSR _m_ re f_2d. 273 

C^R_m_ref_3d. 273 

CMSR_mj*rrite_jtojprocessor_2d. 275 

CMSRjna_write_to_processor_3d. 275 

(3iSR_rotation_constjmatrix_2d. 278 

CMSR_rotation_jaatrix_2d. 280 

CMSR^scale^const^matrix^d . 282 

CMSR_scale__const_matrix_3d . 282 

CMSR_scale_jnatrix_2d. 285 

CMSR_scale_matrix_3d. 285 

04SR_trans_const_matrix_2d . 288 

CaMSR_trans_const_jnatrix_3d . 288 

CMSR_translation_matrix_2d . 291 

CMSR_translation_matrix_3d . 291 

CMSR_x_rotation_const_matrix_3d . 294 

CMSR_y_rotation_const_matrix_3d . 294 

CMSR_z_jcotation_const_matrix__3d . 294 

CMSR_x_rotation_matrix_J3d. 297 

C^R_jf_rotation_matrix_3d. 297 

CMSR z rotation matrix 3d. 297 
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CMSRJdentity_matrix_2d 

CMSRJdentity_matrix_3d 

Loads a 2D (3D) identity matrix into a matrix field. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_identity_matrix_2d ( destjnatrixJield, signifjen, exp Jen) 

void 

CMSR_identity_matrix_3d ( destjnatrixJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield; 
unsigned int signifjen ; 
unsigned int exp Jen ; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_IDENTITY_MATRIX_2D 

& ( destjnatrixJield, signifjen, exp Jen) 

SUBROUTINE CMSR_IDENTITY_MATRIX_3D 

& ( destjnatrixJield, signifjen, exp Jen) 

INTEGER destjnatrixJield 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR: identity-matrix-2d ( dest-matrixjield 

{■optional (signif-len 23) ( exp-len 8)) 

CMSR:identity-matrix-3d (dest-matrixjield 

fioptional ( signif-len 23) ( exp-len 8)) 
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CMSRJdentity_matrix_2d 

CMSR_identity_matrix_3d 
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ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory into 
which the identity matrix is to be written. Each element of the 
matrix is a floating-point value having a length of ( signifjen + 
exp Jen +1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

For CMSR_identity_matrix_2d, destjnatrix Jield accepts a 3 
x 3 homogeneous transformation matrix stored in row-major or¬ 
der. The length of the entire field is 9 * ( signifjen + exp Jen +1). 

For CMSR_identity_matrix_3d the matrix field accepts a 4 x 
4 homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 16 * {signifjen + exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield. 


DESCRIPTION 

CMSR_identity_matrix_2d and CMSR_identity_matrix_3d write a 2D or 3D 
identity matrix, respectively, into destjnatrix Jield in each active processor in the cur¬ 
rent VP set. 


SEE ALSO 

CMSR_fe_identity_matrix_2d 

CMSR_fe_identity_matrix_3d 
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CMSR_m_alloc_heap_field_2d 

CMSR_m__alloc_heap_field_3d 

Allocate a 2D (3D) matrix field in the heap memory space and return its Paris field ID. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 

CM_field_id_t 

CMSR_m_al loc_heap_f ield_2 d ( signifjen, exp Jen) 
unsigned int signifjen, exp Jen ; 

CM_field_id_t 

CMSR_m_alloc_heap_field_3d ( signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_M_ALLOC_HEAP_FIELD_2D 

& (signifjen, exp len) 

INTEGER signifjen, exp Jen 

INTEGER FUNCTION CMSR_M_ALLOC_HEAP_FIELD_3D 

& (signifjen, exp Jen) 

INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:m-alloc-heap-field-2d (signif-len exp—len) 
CMSR:m-alloc-heap-field-3d (signif-len exp-len) 
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CMSR_m_alloc_heap_field_2d 

CMSR_m_alloc_heap_field_3d 


ARGUMENTS 

signifjen The length, in bits, of the significant! of the floating-point values 

to be stored in the returned field. 

exp Jen The length, in bits, of the exponent of the floating-point values to 

be stored in the returned field. 


DESCRIPTION 

CMSR_m_al 1 oc_heap_f ie 1 d_2d and CMSR_m_alloc_heap_f ield_3d allocate a 
matrix in the heap memory space and return its Paris field ID. 

A matrix field is organized to contain a square homogeneous transformation matrix 
stored in row-major order. Each element of the matrix is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

CMSR_m_alloc_heap_field_2d allocates a field for a 3 x 3 matrix. The length of 
the entire field is ( 3 * 3) * ( signifjen + exp Jen + 1). 

CMSR_m_alloc_heap_f ield_3d allocates a field for a 4 x 4 matrix. The length of 
the entire field is ( 4 * 4) * ( signifjen + exp Jen + 1). 


Version 2.0, November 1991 


249 




*Render Reference Manual for Paris 


CMSR_m_alloc_stack_field_2d 

CMSR_m_alloc_stack_field_3d 


CMSR_m_alloc_stack_field__2d 

CMSR_m_alloc_stack_field_3d 

Allocates a 2D (3D) matrix field on the stack memory space and return its Paris field ID. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 

CM_field_id_t 

CMSR_m_alloc_stack_field_2d ( signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 

CM_field_id_t 

CMSR_m_alloc_stack_field_3d (signifjen, exp Jen) 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort. h' 

INTEGER FUNCTION CMSR_M_ALLOC_STACK_FIELD_2D 

& (signifjen, exp Jen) 

INTEGER signifjen, exp Jen 

INTEGER FUNCTION CMSR_M_ALLOC_STACK_FIELD_3D 

& (signifjen, exp Jen) 

INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:m-alloc-stack-field-2d (signif-len exp-len) 
CMSR:m-alloc-stack-field-3d (signif-len exp-len) 
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CMSR_m_alloc_stack_field_2d 

CMSR_m_alloc_stack_field_3d 


ARGUMENTS 

signifjen The length, in bits, of the significand of the floating-point values 

to be stored in the returned field. 

exp Jen The length, in bits, of the exponent of the floating-point values to 

be stored in the returned field. 

DESCRIPTION 

CMSR_m_alloc_stack_field_2d and CMSR_m_alloc_stack_field_3d allo¬ 
cate a matrix on the stack and return its Paris field ID. 

A matrix field is organized to contain a square homogeneous transformation matrix 
stored in row-major order. Each element of the matrix is a floating-point value having a 
length of {signifjen + exp Jen + 1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

CMSR_m_alloc_stack_field_2d allocates a field for a 3 x 3 matrix. The length of 
the entire field is ( 3 * 3) * {signifjen + exp Jen + 1). 

CMSR_m_alloc_stack_field_3d allocates a field for a 4 x 4 matrix. The length of 
the entire field is ( 4 * 4) * {signifjen + exp len + 1). 
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CMSR_m_copy_2d 

CMSR_m_copy_3d 

Copies one 2D (3D) matrix field to another. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_m_copy_2d (destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield, srcjnatrixJield ; 
unsigned int signifjen, exp Jen; 

void 

CMSR_m_copy_3d (destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield, srcjnatrixJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_C0PY_2D 

& ( destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

INTEGER destjnatrixJield, srcjnatrixJield, signifjen, exp Jen 

SUBROUTINE CMSR_M_COPY_3D 

& ( destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

INTEGER destjnatrixJield, srcjnatrixJield, signifjen, exp Jen 


Lisp Syntax 

CMSR:m-copy-2d (dest-matrix-field src-matrixjield 

{■optional ( signif-len 23) ( exp-len 8)) 

CMSR:m-copy-3d (dest-matrix-field src-matrix-field 

{■optional (signif-len 23) (exp-len 8)) 
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CMSR_m_copy_2d 

CMSR_m_copy_3d 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the matrix field in CM memory 
into which the srcjnatrixJield is to be copied, destjnatrixJield 
must be in the same VP set as srcjnatrix Jield. 

srcjnatrix Jield A Paris field indentifier specifying the matrix field in CM memory 

to be copied into destjnatrix Jield. srcjnatrix Jield must be in 
the same VP set as destjnatrixJield. 

For CMSR_m_copy_2d these matrix fields contain a 3 x 3 
homogeneous transformation matrix stored in row-major order. 
Each element of the matrix is a floating-point value having a 
length of (signiflen + exp len +1), where signiflen is the length 
of the significant!, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is (3 * 3) * (signif len 
+ exp Jen +1). 

For CMSR_m_copy_3d these matrix fields contain a 4 x 4 
homogeneous transformation matrix stored in row-major order. 
Each element of the matrix is a floating-point value having a 
length of (signiflen + exp Jen +1), where signiflen is the length 
of the significant!, exp len is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is (4 * 4) * (signif len 
+ exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrix Jeld and srcjnatrix Jeld. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrix Jeld and srcjnatrix Jeld. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_m_copy_2d and CMSR_m_ 
c°py_3d copy srcjnatrixJeld to destjnatrixJeld. Both fields must be in the cur¬ 
rent VP set. 
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CMSR_m_copy_const_2d 
CMSR_m_copy_const_3d 

Broadcasts a front-end 2D (3D) matrix into a CM matrix field. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_m_copy_const_2d 

(i destjnatrixjield, srcjnatrix, signifjen, expjen) 

CM_field_id_t destjnatrixJield; 
double srcjnatrix [ 3] [3] / 

unsigned int signifjen, exp Jen; 

void 

CMSR_m_copy_cons t_3d 

(< destjnatrixJield, srcjnatrix, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield; 
double srcjnatrix [4] [4]; 

unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_COPY_CONST_2D 

& ( destjnatrixJield, srcjnatrix, signifjen, exp Jen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION srcjnatrix (3 , 3) 

INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_M_COPY_CONST_3D 

& ( destjnatrixJield, srcjnatrix, signifjen, exp Jen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION srcjnatrix (4,4) 

INTEGER signifjen, exp Jen 
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Lisp Syntax 

CMSR:m-copy-const-2d ( dest-matrix-field src-matrix 

Soptional ( signif-len 23) (exp-len 8)) 

CMSR:m-copy-const-3d (dest-matrix-field src-matrix 

&optional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the matrix field in CM memory 
into which the srcjnatrix is to be copied. Each element of the 
matrix is a floating-point value having a length of (signifjen + 
exp Jen +1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

For CMSR_m_copy_2d this matrix field contains a 3 x 3 homoge¬ 
neous transformation matrix stored in row-major order. The 
length of the entire field is (3 * 3) * (signifjen + exp Jen +1). 

For CMSR_m_copy_3d this matrix field contains a 4 x 4 homoge¬ 
neous transformation matrix stored in row-major order. The 
length of the entire field is (4 * 4) * (signifjen + exp Jen + 1). 

srcjnatrix A two-dimensional front-end array containing the matrix of 

floating-point values to be broadcast to destjnatrixJield. 

For CMSR_m_copy_2d, srcjnatrix is a 3 x 3 array. 

For CMSR_m_copy_3d, srcjnatrix is a 4 x 4 array. 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield. 


DESCRIPTION 

CMSR_m_copy_const_2d and CMSR_m_copy_const_3d copy the front-end matrix 
srcjnatrix into destjnatrixJield in each active processor in the current VP set. 
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CMSR_m_determinant_2d 

CMSR_m_determinant_3d 

Calculates the determinant of each 2D (3D) matrix stored in a matrix field. 


SYNTAX 

C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_m_determinant_2d ( determJield, matrixJeld, signifjen, exp Jen) 

void 

CMSR_m_deterniinant_3d (determJield, matrixJeld, signifjen, exp Jen) 

CM_fie 1 d_id_t determJeld, matrixJeld; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_DETERMINANT_2D 

& (determJeld, matrixJield, signifjen, exp Jen) 

SUBROUTINE CMSR_M_DETERMINANT_3D 

& (determJeld, matrixJeld, signifjen, exp Jen) 

INTEGER determ Jeld, matrixJeld 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:m-determinant-2d (determjeld, matrix-field 

&optional (signif-len 23) (exp-len 8)) 

CMSR:m-determinant-3d (determ-field, matrix-field 

soptional (signif-len 23) (exp-len 8)) 
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CMSR_m_determinant_2d 

CMSR_m_determinant_3d 


ARGUMENTS 

determJield 


matrixJield 


signifjen 


exp Jen 


A Paris field identifier specifying the field in CM memory into 
which the matrix determinant is to be stored. The length of the 
field is {signifjen + exp Jen +1) bits, where signiflen is the 
length of the significand, exp Jen is the length of the exponent, 
and 1 is the sign bit. 

A Paris field identifier specifying the matrix field in CM memory 
containing the matrices for which the determinant is to be 
calculated. Each element of the matrix is a floating-point value 
having a length of {signifjen + exp Jen + 1), where signifjen is 
the length of the significand, exp Jen is the length of the exponent, 
and 1 is the sign bit. 

For CMSR_m_determinant_2d this matrix field contains a 3 x 3 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 9 * {signiflen + exp Jen +1). 

For CMSR_m_determi.nant_3d this matrix field contains a 4 x 4 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 16 * {signif len + exp len +1). 

The length, in bits, of the significand of the floating-point values 
in determ Jield and matrix Jield. 

The length, in bits, of the exponent of the floating-point values in 
determ Jield and matrix Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_m_determinant_2d and 
CMSR_m_determinant_3d calculate the determinant of the matrix stored in 
matrixJield and place it in determ Jield. 
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CMSR_m_fieldJength 

Returns the length of a matrix field of a specified rank. 


SYNTAX 
C Syntax 


#indude <cm/cmsr.h> 
int 

CMSR_m_field_length ( rank, signifjen, exp Jen) 
int rank; 

unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 

INTEGER FUNCTION CMSR_M_FIELD_LENGTH (rank signifjen expjen) 

INTEGER rank; 

INTEGER signifjen; 

INTEGER expjen; 


Lisp Syntax 

CMSR:m-field-length (rank fioptional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

rank 


The number of dimensions in the matrix for which the field is 
allocated. 


signifjen The length, in bits, of the significand of the floating-point values 

in the field. 


expjen The length, in bits, of the exponent of the floating-point values in 

die field. 
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CMSR_m_fieldJength 


DESCRIPTION 

CMSR_m_field_length returns the length, in bits, of the Paris field that must be alio 
cated to hold a matrix of (1 + rank) elements square. 


SEE ALSO 

CMSR_v_field_length 
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CMSR_m_invert_2d 

CMSR_m_invert_3d 

Calculates the inverse of each 2D (3D) matrix in the matrix field. 


SYNTAX 
C Syntax 

finclude <cm/cmsr.h> 
void 

CMSR_m_invert_2d 

(destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

void 

CMSR_m_invert_3d 

{destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield, srcjnatrixJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_INVERT_2D 

& {destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

SUBROUTINE CMSR_M_INVERT_3D 

& {destjnatrixJield, srcjnatrixJield, signifjen, exp Jen) 

INTEGER destjnatrixJeld, srcjnatrixJeld; 

INTEGER signifjen, exp Jen; 


Lisp Syntax 

CMSR:m-invert-2d {dest-matrix-field src-matrix-field 

^optional {signif-len 23) {exp-len 8)) 

CMSR: m-invert-3d {dest-matrix-field src-matrix-field 

fioptional {signif-len 23) {exp-len 8)) 
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ARGUMENTS 


destjnatrixJteld A Paris field identifier specifying the matrix field in CM memory 
in which the inverted matrices are to be stored, destjnatrixJield 
must be in the same VP set as srcjnatrixJield. 

srcjnatrixJield A Paris field indentifier specifying the matrix field in CM memory 

containing the matrices to be inverted, srcjnatrixJield must be in 
the same VP set as destjnatrixJield. 

Each element of the matrix is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length 
of the significand, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is (4*4)* ( signifjen 
+ exp Jen +1). 

For CMSR_m_copy_2d these matrix fields contain a 3 x 3 
homogeneous transformation matrix stored in row-major order. 
For CMSR_m_copy_3d these matrix fields contain a 4 x 4 
homogeneous transformation matrix stored in row-major order. 


signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrixJield and srcjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield and srcjnatrixJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_m_invert_2d and 
CMSR_m_invert_3d calculate the inverse of src jnatrix Jield and store the result in 
destjnatrix Jield. Both fields must be in the current VP set. destjnatrixJield may be 
the same field as srcjnatrixJield, or the fields may be totally disjoint. However, par¬ 
tially overlapping fields cause unpredictable results. 

NOTE: If srcjnatrixJield in some processor is singular (that is, if the matrix determi¬ 
nant is zero) the contents of destjnatrixJield for that processor are undefined. 
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CMSR_m_multiply_2d 

CMSR_m_multiply_3d 

Multiplies two 2D (3D) matrices. 


SYNTAX 
C Syntax 


#include <cm/cmsr.h> 


void 

CMSR_m_multiply_2d 

(dest matrixJield, srcl matrixJield, src2jnatrixJield, 
signifjen., exp Jen) 


void 

CMSR_m_multiply_3d 

(i destjnatrixJield, srcl jnatrixJield, src2 matrixJield, 
signifjen, exp Jen) 


CM_field_id_t 
CM_field_id_t 
CM_field_id_t 
unsigned int 
unsigned int 


destjnatrixJeld; 
srcl jnatrixJeld; 
src2jnatrixJeld; 
signifjen; 
exp len; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_MULTIPLY_2D 

s ( destjnatrixJeld, srcl jnatrixJeld, src2jnatrixJeld, signifjen , exp Jen) 

SUBROUTINE CMSR_M_MULTIPLY_3D 

& ( destjnatrixJeld, srcl jnatrixJeld, src2matrixJeld, signifjen, exp Jen) 

INTEGER destjnatrixJeld 
INTEGER srcl jnatrixJeld 
INTEGER src2jnatrixJeld 
INTEGER signifjen 
INTEGER exp Jen 
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CMSR_m_multiply_2d 

CMSR_m_multiply_3d 


Lisp Syntax 

CMSR : m-multiply-2d (dest-matrixJield srcl-matrix-field src2-matrix-field 
^optional (signif-len 23) ( exp-len 8)) 

CMSR : m-multiply-3d (dest-matrix-field srcl-matrix-field src2-matrix-field 
Soptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory into 
which the resulting 2D matrix is to be written. Each element of the 
matrix is a floating-point value having a length of ( signifjen + 
exp Jen +1), where signiflen is the length of the significance 
exp Jen is the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * ( signifjen + exp Jen +1). 

The 3D matrix field contains a 4 x 4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * ( signifjen + exp Jen +1). 

destjnatrix Jield must be in the same VP set as srcljnatrixJield 
and src2matrixJield. 

srcljnatrixJield, src2jnatrixJield 

Paris field indentifiers specifying the fields in CM memory 
containing the 2D matrices to be multiplied. Each element of the 
matrix is a floating-point value having a length of ( signifjen + 
exp Jen +1), where signifjen is the length of the significant!, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * ( signifjen + exp Jen + 1). 

The 3D matrix field contains a 4 x 4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * ( signifjen + exp Jen + 1). 

srcljnatrixJield and src2jnatrixJield must be in the same VP 
set as destjnatrixJield. 
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signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrix Jield, srcljnatrixJield, and src2jnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield, srcljnatrixJield, and src2jnatrixJield. 


DESCRIPTION 

For each active processor, CMSR_m_multiply_2d and CMSR_m_multiply_3d 
calculate the product of the two matrices {srcjnatrixJieldJ * srcjnatrix JieldJS) 
and write the result in destjnatrixJield. 

All fields must be in the current VP set. The destjnatrixJield and srcjnatrixJield J 
may be the same field or totally disjoint fields, but the fields must not overlap. Partial 
overlap may cause unpredictable results. 


SEE ALSO 

CMSR_m_multiply_const_2d 
CMSR_m_multiply_const_3d 
CMSR_fe_m_multiply_2d 
CMSR_fe_m_multiply_3d 
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CMSR_m_multiply_const_2d 

CMSR_m_multiply_const_3d 


CMSR_m_multiply_const_2d 

CMSR_m_multiply_const_3d 

Multiplies a single 2D (3D) matrix with a 2D (3D) matrix field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_m_multiply__const_2d 

(i destjnatrixJield, srcmatrixJield, matrix, signifjen exp Jen) 

CM_field_id_t destjnatrixJield, srcjnatrixJield; 
double matrix [ 3 ] [ 3 ]; 

unsigned int signifjen, exp Jen; 

void 

CMSR_m_multiply_const_3d 

( destjnatrixJield, src matrixJield, matrix, signifjen exp len) 

CM_field_id_t destjnatrixJield, src matrixJield; 

double matrix[ 4] [4]; 

unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

CMS R_M_MULTIPLY_CONST_2D 

( destjnatrixJield, srcjnatrixJield, matrix, signifjen, exp Jen) 

INTEGER destjnatrixJield, srcjnatrixJield 

DOUBLE PRECISION matrix (3) (3) 

INTEGER signifjen, exp Jen 

CMSR_M_MULTIPLY_C0NST_3D 

(destjnatrixJield, srcjnatrixJield, matrix, signifjen exp Jen) 

INTEGER destjnatrixJield, srcjnatrixJield 

DOUBLE PRECISION matrix (4) (4) 

INTEGER signifjen, exp Jen 
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CMSR_m_multlply_const_2d 

CMSR_m_multlply_const_3d 


Lisp Syntax 

CMSR: m-multiply-const-2d (dest-matrix-field src-matrix-field matrix 

&optional ( signif-len 23) ( exp-len 8)) 

CMSR: m-multiply-cons t-3d ( dest-matrix-field src-matrix-field matrix 

(optional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the result is written, destjnatrix Jield must be in the same 
VP set as srcjnatrixJield. Each element of the matrix is a 
floating-point value having a length of ( signifjen + exp Jen +1), 
where signifjen is the length of the significand, exp Jen is the 
length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * ( signifjen + exp Jen + 1). 

The 3D matrix field contains a 4 x 4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * ( signifjen + exp Jen + 1). 

srcjnatrixJield A Paris field identifier specifying the field in CM memory from 

which the matrix to be transformed is taken. Each element of the 
matrix is a floating-point value having a length of ( signifjen + 
exp Jen + 1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * {signifjen + exp Jen + 1). 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. The length of die entire field is 
16 * {signifjen + exp Jen + 1). 

matrix A 3 x 3 homogeneous transformation matrix stored on the 

front-end computer in row-major order. Each element of the 
matrix is a double-precision floating-point value. 

signifjen The length, in bits, of the significand of the floating-point values 

in srcjnatrixJield and destjnatrixJield. 
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CMSR_m_multiply_const_2d 

CMSR_m_multiply_const_3d 


exp Jen The length, in bits, of the exponent of the floating-point values in 

srcjnatrixJield and destjnatrixJield. 


DESCRIPTION 

CMSR_m_multi.ply_const._2d and CMSR_m_multiply_const_3d multiply the 
transformation matrix matrix with the matrix in each active processor in srcjnatrix_ 
field and store the result in destjnatrixJield. 

All fields must be in the current VP set. The dest matrix Jield may be the same field as 
srcjnatrixJield, or the fields may be totally disjoint. However, partially overlapping 
fields cause unpredictable results. 


SEE ALSO 

CMSR_m_multiply_2d 
CMSR_m_multiply-3d 
CMSR_fe_m_multiply_2d 
CMSR_fe_m_multiply_3d 
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CMSR__m_print_2d 

CMSR_m_print_3d 

Prints on stdout the contents of 2D (3D) matrix in a given processor. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_m_p r i n t_2d ( processor, srcjnatrixJield, signifjen, exp Jen) 

void 

CMSR_m_p r int_3d ( processor, srcjnatrixJield, signifjen, exp Jen) 

unsigned int processor; 

CM_f ield_id_t srcjnatrixJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_PRINT_2D 

& (processor, srcjnatrixJeld, signifjen, exp Jen) 

SUBROUTINE CMSR_M_PRINT_3D 

& (processor, srcjnatrixJeld, signifjen, exp Jen) 

INTEGER processor 
INTEGER srcjnatrixJeld 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:m-print-2d (processor src-matrixjeld 

fioptional (signif-len 23) (exp-len 8)) 

CMSR:m-print-3d (processor src-matrixjeld 

^optional (signif-len 23) (exp-len 8)) 
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CMSR_m_print_3d 


ARGUMENTS 

processor The send address of the processor from which you wish to print 

the matrix. 

srcjnatrixJield A Paris field identifier specifying the matrix field in CM memory 

containing the matrix to be copied. 

For CMSR_m_copy_2d this matrix field contains a 3 x 3 homoge¬ 
neous transformation matrix stored in row-major order. 

For CMSR_m_copy_3d this matrix field contains a 4 x 4 homoge¬ 
neous transformation matrix stored in row-major order. 

Each element of the matrix is a floating-point value having a 
length of ( signifjen + exp len +1), where signifjen is the length 
of the significant!, exp len is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is (4 * 4) * {signifjen 
+ exp Jen + 1). 

signifjen The length, in bits, of the significand of the floating-point values 

in src jnatrix Jield. 

exp len The length, in bits, of the exponent of the floating-point values in 

srcjnatrixJield. 


DESCRIPTION 

CMSR_m_p r in t_2d and CMSR_m_print_3d print on stdout the double-precision 
floating-point contents of src jnatrix Jield in the given processor. 

The matrix elements are printed one row per line, separated by spaces, and followed by 
a carriage return. 
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CMSR__m_read_from_processor_2d 

CMSR_m_read_from_processor_3d 

Reads a 2D (3D) matrix field from a specified processor into a front-end array. 


SYNTAX 
C Syntax 

#includa <cm/cmsr.h> 
void 

CMSR_m_read_from_processor_2d 

( processor, srcjnatrixJield, destjnatrix, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t srcjnatrixJield; 
double destjnatrix [3] [3]; 

unsigned int signifjen, exp Jen; 

void 

CMSR_m_read_from_processor_3d 

( processor, srcjnatrixJield, destjnatrix, signifjen . exp Jen) 

unsigned int processor; 

CM_field_id_t srcjnatrixJield; 
double destjnatrix [4] [4] ; 

unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_M_READ_FR0M_PR0CESS0R_2D 

& {processor, srcjnatrixJield, destjnatrix, signifjen , exp Jen) 

INTEGER processor 

INTEGER srcjnatrixJield 

DOUBLE PRECISION destjnatrix {3,3) 

INTEGER signifjen 

INTEGER exp Jen 
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SUBROUTINE CMSR_M_READ_FROM_PROCESSOR_3D 

& (processor, srcjnatrixJield, destjnatrix, signifjen, exp Jen) 

INTEGER processor 

INTEGER srcjnatrixJield 

DOUBLE PRECISION destjnatrix (4,4) 

INTEGER signifjen 

INTEGER exp len 


Lisp Syntax 

CMSR:m-read-from-processor-2d 

(processor src-matrix-field 
fioptional matrix (signif-len 23) (exp-len 8)) 

CMSR:m-read-from-processor-3d 

(processor src-matrix-field 
fioptional matrix (signif-len 23) (exp-len 8)) 


ARGUMENTS 

processor The send address of the processor from which the matrix is to be 

read. 

srcjnatrixJield A Paris field indentifier specifying the field in processor from 

which the 3D matrix is to be read. 

The 2D matrix field contains a 3 x3 homogeneous transformation 
matrix, and the 3D matrix field contains a 4 x 4 homogeneous 
transformation matrix. The elements of the matrix are stored in 
row-major order. Each element of the matrix is a floating-point 
value having a length of ( signifjen + exp len +1), where 
signifjen is the length of the significand, exp Jen is the length of 
the exponent, and 1 is the sign bit. The length of the entire field 
is 16 * (signifjen + exp Jen + 1). 

destjnatrix A 3 x 3 array for CMSR_m_read_from_processor_2d and a 4 

x 4 array for CMSR_m_read_f rom_processor_3d in which the 
matrix is to be returned. 

signifjen The length, in bits, of the significand of the floating-point values 

in srcjnatrixJield. 
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CMSR_m_read_from_processor_2d 

CMSR_m_read_from_processor_3d 

mmmmmmmmMmmmmmmmmmmmmmmmmmmmm 


exp Jen The length, in bits, of the exponent of the floating-point values in 

srcjnatrixJield. 


DESCRIPTION 

CMSR_m_read_from_jprocessor_2d and CMSR_m_read_from_processor_3d 

read the contents of srcjnatrixJield from the given processor and store the matrix 
elements in the front-end array destjnatrix. 


SEE ALSO 

CMSR_m_write_tojprocessor_2d 
CMSR_m_wri te_to_jproces sor_3d 
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CMSR_m_ref_2d 

CMSR_m_ref__3d 

Returns the field ID of a specified element of a 2D (3D) matrix. 

SYNTAX 
C Syntax 

#indude <cm/cmsr.h> 

CM_field_id_t 

CMSR_m_ref_2d (matrixJield, row column, signifjen, exp Jen) 

CM_field_id_t 

CMSR_m_ref_3d (matrixJield, row, column, signifjen, expjen) 

CM_field_id_t matrixJield; 
unsigned int row; 
unsigned int column; 
unsigned int signifjen; 
unsigned int expjen; 

Fortran Syntax 

INCLUDE ’ /usr/include/cm/cmsr-math-fort.h' 

INTEGER FUNCTION CMSR_M_REF_2D 

& (matrixJield, row, column, signifjen, expjen) 

INTEGER FUNCTION CMSR_M_REF_3D 

& (matrixJeld, row, column, signifjen, expjen) 

INTEGER matrixJield 
INTEGER row 
INTEGER column 
INTEGER signifjen 
INTEGER expjen 
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Lisp Syntax 


GMSR:m-ref-2d 

CMSR:m-ref-3d 

(matrix-field row column 

fioptional ( signif-len 23) (exp-len 8)) 

( matrix-field row column 
soptional (signif-len 23) ( exp-len 8)) 

ARGUMENTS 


matrixJield 

The Paris field ID of the matrix from which the matrix element 
specified by (row, column) is to be referenced. Each element of 
the matrix is a floating-point value having a length of ( signifjen 
+ exp Jen +1), where signifjen is the length of the significant!, 
exp Jen is the length of the exponent, and 1 is the sign bit. 


CMSR_m_ref_2d references a 2D matrix field containing a 3 x 3 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 9 * ( signifjen + exp Jen + 1). 


CMSR_m_ref_3d references a 3D matrix field containing a 4x4 
homogeneous transformation matrix stored in row-major order. 
The length of the entire field is 16 * ( signif jen + elen +1). 

row 

The row position of the element to be returned. Matrices are stored 
in row-major order. 

column 

The column position of the element to be returned. 

signifjen 

The length, in bits, of the significand of the floating-point values 
in the field. 

explen 

The length, in bits, of the exponent of the floating-point values in 
the field. 

DESCRIPTION 


CMSR_m_ref_2d and CMSR_m_ref_3d return the field ID for the subfield of 
matrix Jield in which the element (row, column) is stored. 


274 


Version 2.0, November 1991 




CMSR_m_write_to_processor_2d 
Chapter ! Math Routines CMSR_m_write_to_processor_3d 

CMSR_m_write_to_processor_2d 

CMSR_m_write_to_processor_3d 

Writes a 2D (3D) matrix from a front-end array into a matrix field on a specified processor. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR_m_write_tojprocessor_2d 

(processor, destjnatrixJield, srcjnatrix, signifjen, exp Jen) 

unsigned int processor; 

CM__field_id_t destjnatrixJield; 
double srcjnatrix [3] [3]; 

unsigned int signifjen, exp Jen; 

void 

CMSR^m_w r i te_t°_pr oee s sor_3d 

(processor, destjnatrixJeld, srcjnatrix, signifjen, exp Jen) 

unsigned int processor; 

CM_field_id_t destjnatrixJeld; 
double srcjnatrix [ 4 ] [ 4 ] ; 

unsigned int signifjen, exp Jen; 

Fortran Syntax 

INCLUDE ' /usr/include/can/cmsr-math-fort. h' 

SUBROUTINE CMSRJM_WRITE_TO_PROCESSOR_2D 

& (processor, destjnatrixJeld , srcjnatrix , signifjen, exp Jen) 

INTEGER processor 

INTEGER destjnatrixJeld 

DOUBLE PRECISION srcjnatrix (3 ,3) 

INTEGER signifjen , exp Jen 
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SUBROUTINE CMSR_M_WRITE_TO_PROCESSOR_3D 

& [processor destjnatrixJield srcjnatrix signifjen exp Jen) 

INTEGER processor 

INTEGER destjnatrixJield 

DOUBLE PRECISION srcjnatrix (4 , 4) 

INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:m-write-to-processor-2d [processor dest-matrix-field src-matrix 

[signif-len 23) [exp-len 8)) 

CMSR:m-write-to-processor-3d [processor dest-matrix-field src-matrix 

[signif-len 23) [exp-len 8)) 


ARGUMENTS 

processor The processor send address to which the matrix is to be sent. 

dest matrixJield A Paris field indentifier specifying the field in processor in which 
the srcjnatrix is to be stored. 

Each element of the matrix is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length 
of the significand, exp len is the length of the exponent, and 1 is 
the sign bit. The elements are stored in row-major order. 

The 2D matrix field must be large enough for a 3 x3 matrix; the 
length of the field must be at least 9 * [signifjen + exp Jen + 1). 

The 3D matrix field must be large enough for a 4 x4 matrix; the 
length of the field must be at least 16 * [signifjen + exp Jen +1). 

srcjnatrix For CMSR_m_read_from_processor_2d a 3 x 3 array and for 

CMSR_m_ read_from_processor_3d a 4 x 4 array, that is to 
be broadcast to destjnatrixJield. 

signifjen The length, in bits, of the significand of the floating-point values 

in matrix Jeld. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

matrixJeld. 
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CMSR_m_wrIte_to_processor_2d 

CMSR_m_write_to_processor_3d 


DESCRIPTION 

CMSR_m_read_from_processor_2d and CMSR_m_write_to_processor_3d 

place the contents of srcjnatrix in dest_matrix-field on the specified processor. 


SEE ALSO 

CMSR_m_read_f rom_proces sor_2 d 
CMSR_m_read_£ romjprocessor_3d 
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CMSR_rotation_const_matrix_2d 

Inserts specified rotation into a 2D transformation matrix field. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_rotation_const_matrix_2d 

(i destjnatrixJield, theta, signifjen, exp Jen) 
CM_field_id_t destjnatrixJield; 
double theta ; 

unsigned int signifjen; 
unsigned int exp Jen ; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_R0TATI0N_C0NST_MATRIX_2D 

& ( destjnatrixJield, theta, signifjen, exp Jen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION theta 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR:rotation-const-matrix-2d 

( dest-matrix-field theta 
fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the 2D transformation matrix is to be returned. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. Each element of the matrix is a 
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CMSR_rotation_const_matrix_2d 

floating-point value having a length of {signifjen + expjen + 1), 
where signifjen is the length of the significand, expjen is the 
length of the exponent, and 1 is the sign bit. The length of the 
entire field is 9 * ( signifjen + expjen +1). 

theta A double-precision value on the front-end computer, theta is the 

rotation in radians to be incorporated into the transformation 
matrix in destjnatrixJield. 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrixJield. 

expjen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_rotation_const_ 
matrix_2d creates a two-dimensional rotation matrix in destjnatrixJield by setting 
the field to an identity matrix and then inserting a rotation of theta radians. All fields 
must be in the current VP set. 

SEE ALSO 

CMSR_rotation_matri.x_2d 

CMSR_x_rotation_cons t_matrix_3d 

CMSR_x_rotation_matrix_3d 

CMSR_y_ro ta tion_const_matrix_3d 

CMSR_y_rotation_matrix_3d 

CMSR_z_rotation_const_matrix_3d 

CMSR_z_rotation_matrix_3d 

CMSR_fe_rotation_matrix_2d 

CMSR_fe_x_rotation_matrix_3d 

CMSR_fe_y_rotation_matrix_3d 

CMSR fe z rotation matrix 3d 
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CMSR_rotation_matrix_2d 

Inserts field of 2D rotation values into a transformation matrix field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_rotation_matrix_2d 

(destjnatrixJield, thetaJield, signifjen, exp Jen) 
CM_field_id_t destjnatrixJield; 

CM_field_id_t thetaJield; 
unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cansr-math-fort.h' 

SUBROUTINE CMSR_R0TATI0N_MATRIX_2D 

& ( destjnatrixJield, thetaJield, signifjen, exp len) 

INTEGER destjnatrixJield 
INTEGER thetaJield 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR:rotation-matrix-2d ( dest-matrixJield theta Jield 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrix Jeld A Paris field identifier specifying the field in CM memory to 
which the 2D transformation matrix is to be returned. 

The 2D matrix field contains a 3 x3 homogeneous transformation 
matrix stored in row-major order. Each element of die matrix is a 
floating-point value having a length of {signifjen + exp Jen + 1), 
where signifjen is the length of the significand, exp Jen is the 
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length of the exponent, and 1 is the sign bit. The length of the 
entire field is 9 * ( signifjen + exp Jen + 1). 

thetaJield A Paris field identifier specifying the field in CM memory 

containing the the rotation angle, in radians, to be inserted into 
dest_matrixJield. theta Jield must be in the same VP set as 
destjnatrixJield. 

thetaJield is a floating-point value of length {signifjen + exp Jen 
+ 1 + color Jen), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

signifjen The length, in bits, of the significand of the floating-point values 

in thetaJield and destjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

theta Jield and destjnatrix Jield. 

DESCRIPTION 

For each active processor, CMSR_rotation_matrix_2d creates a two-dimensional 
rotation matrix by setting the transformation matrix in destjnatrixJield to an identity 
matrix and then inserting a rotation of theta Jield radians. All fields must be in the 
current VP set. 

SEE ALSO 

CMSR_rotation_const_matrix_2d 

CMSR_x_rotation_const_matrix_3d 

CMSR_x_rotation_matrix_3d 

CMSR_y_rotation_cons t_matrix_3d 

CMSR_y_rotation_matrix_3d 

CMSR_z_rotation_const_matrix_3d 

CMSR_z_rota tion_matri x_3d 

CMSR_fe_rotation_matrix_2d 

CMSR_fe_x_rotation_matrix_3d 

CMSR_fe_y_rotation_matrix_3d 

CMSR fe z rotation matrix 3d 
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CMSR_scale_const_matrix_2d 

CMSR_scale_const_matrix__3d 

Inserts specified 2D (3D) scaling terms into a transformation matrix field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_scale_const_matrix_2d 

{dest_matrix_ field, sx, sy, signifjen, expjen) 

CM_field_id_t destmatrixJield; 
double sx, sy; 

unsigned int signifjen; 
unsigned int expjen ; 


void 

CMSR_s cale_cons t_matrix_3d 

( dest_matrix_ field, sx, sy, sz, signifjen, expjen) 


CM_fie1d_i d_t 
double 

unsigned int 
unsigned int 


dest matrix Jield; 
sx, sy, sz; 
signifjen; 
expjen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort. h' 

SUBROUTINE CMSR_SCALE_CONST_MATRIX_2D 

& {destjnatrix_field, sx, sy, signifjen, expjen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION SX, sy 
INTEGER signifjen 

INTEGER expjen 


282 


Version 2.0, November 1991 




Chapter 3. Math Routines 


CMSR_scale_const_matrix_2d 

CMSR_scale_const_matrix_3d 


& 


SUBROUTINE CMSR_SCALE_CONST_MATRIX_3D 

( destjnatrix_ field, sx, sy, sz, signifjen, exp Jen) 


INTEGER destjnatrixJield 

DOUBLE PRECISION SX, sy, SZ 
INTEGER signifjen 

INTEGER exp Jen 


Lisp Syntax 


CMSR: scale-const-matrix-2d (dest-matrix-field sx sy 

soptional ( signif-len 23) ( exp-len 8)) 

CMSR: scale-const-matrix-3d (dest-matrix-field sx sy sz 

Soptional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the transformation matrix is to be written. Each element of 
the matrix is a floating-point value having a length of ( signifjen 
+ exp Jen + 1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * ( signifjen + exp Jen + 1). 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * ( signifjen + exp Jen + 1). 

sx A double-precision value on the front-end computer, sx is the 

scaling value for the x axis to be incorporated into the 
transformation matrix in destjnatrixJeld. 

sy A double-precision value on the front-end computer, sy is the 

scaling value for the x axis to be incorporated into the 
transformation matrix in destjnatrix Jeld. 

sz A double-precision value on the front-end computer. For 

CMSR_scale_const_matrix_3d, sz is the scaling value for the 
z axis to be incorporated into the transformation matrix in 
destjnatrixJeld. 
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signifjen 
exp Jen 


DESCRIPTION 

CMSR_scale_const_matrix_2d cretates a two-dimensional scaling matrix by set¬ 
ting the transformation matrix in destjnatrixJield to an identity matrix and then 
inserting the scaling terms sx and sy. 

CMSR_scale_const_matrix_3d creates a three-dimensional scaling matrix by set¬ 
ting the transformation matrix in destjnatrixJield to an identity matrix and then 
inserting the scaling terms sx, sy, and sz. 

All fields must be in the current VP set. 


The length, in bits, of the significand of the floating-point values 
in destjnatrixJield. 

The length, in bits, of the exponent of the floating-point values in 
destjnatrixJield. 


SEE ALSO 

CMSR_scale_const_matrix_3d 
CMSR_scale_matrix_2d 
CMSR_scale_matrix_3d 
CMSR_fe_scale_matrix_2d 
CMSR fe scale matrix 3d 
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CMSR_scale_matrix_3d 


CMSR_scale_matrix_2d 

CMSR__scale_matrix_3d 

Inserts fields of 2D (3D) scaling terms into a transformation matrix field. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_scale_matrix_2d 

( destjnatrix_ fieldsxJield, syJield, signifjen, exp len) 

CM_field_id_t dest_matrixJield; 

CM_field_id_t sxJield, syJield; 
unsigned int signifjen; 
unsigned int exp Jen; 

void 

CMSR_scale_matrix_3d 

(destjnatrixfield, sxJield, syJield, szJeld, signifjen, exp Jen) 

CM_field_id_t destmatrixJeld; 

CM_field_id_t sxJeld, syJeld, szJeld; 
unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 


INCLUDE '/usr/include/cm/cmsr-math-fort.h' 


& 


SUBROUTINE CMSR_SCALE_MATRIX_2D 

( dest_matrix_ field, sxJeld, syJeld, signifjen, exp Jen) 


INTEGER destjnatrixJeld 
INTEGER sxJeld, sy Jeld 
INTEGER signifjen 
INTEGER exp Jen 
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& 


CMSR_SCALE_MATRIX_3D 

( destjnatrix_ field, sxJield, syJield, szJield, signifjen, exp Jen) 


INTEGER destjnatrixJield 
INTEGER sxJield, syJield, szJield 
INTEGER signifjen 
INTEGER exp Jen 


Lisp Syntax 

CMSR:scale-matrix-2d (dest-matrixJield sx Jield sy Jield 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR: scale-matrix-3d ( dest-matrixjield sx Jield sy Jield sz Jield 

fioptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory 
containing a 2D transformation matrix. Each element of the matrix 
is a floating-point value having a length of ( signifjen + exp Jen 
+ 1), where signifjen is the length of the significand, exp Jen is 
the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * {signifjen + exp Jen +1). 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * {signifjen + exp Jen + 1). 

sxJield A Paris field identifier specifying the field in CM memory 

containing the x coordinate scaling value to be inserted into 
destjnatrix Jield. sx Jield must be in the same VP set as 
destjnatrixJield. 

sxJield is a floating-point value of length {signifjen + exp Jen + 
1 +colorJen), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

syJield A Paris field identifier specifying the field in CM memory 

containing the y coordinate scaling value to be inserted into 
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destjnatrix_Jield. sy Jeld must be in the same VP set as 
destjnatrixJield. 

syJield is a floating-point value of length (signifjen + exp Jen + 
1 + color Jen), where signifjen is the length of the significand, 
exp Jen is the length of the exponent and 1 is the sign bit. 

sz Jield For CMSR_scale_matrix_3d, a Paris field identifier specifying 

the field in CM memory containing the z coordinate scaling value 
to be inserted into destjnatrix Jeld. sz Jield must be in the same 
VP set as destjnatrix Jield. 

szJeld is a floating-point value of length {signifjen + exp Jen + 
1 + color Jen), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

signifjen The length, in bits, of the significand of the floating-point values 

in sx Jeld, sy Jeld, and dest jnatrix Jeld. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

sx Jeld, syJeld, and destjnatrixJeld. 


DESCRIPTION 

For each active processor, CMSR_scale_matrix_2d creates a two-dimensional scal¬ 
ing matrix by setting the transformation matrix in destjnatrix Jeld to an identity 
matrix and then inserting the scaling terms from sx Jeld and sy Jeld. 

For each active processor, CMSR_scale_matrix_3d creates a three-dimensional 
scaling matrix by setting the transformation matrix in destjnatrix Jeld to an identity 
matrix and then inserting the scaling terms from sx Jeld, sy Jeld, and sz Jeld. 

All fields must be in the current VP set. 

SEE ALSO 

CMSR_scale_const_matrix_2d 
CMSR_scale_const_matrix_3d 
CMSR_fe_scale_matrix_2d 
CMSR fe scale matrix 3d 
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CMSR_trans_const_matrix_2d 

CMSR_trans_const_matrix_3d 

Inserts 2D (3D) translation terms into a transformation matrix field. 


SYNTAX 
C Syntax 

#±nclude <cm/cmsr.h> 
void 

CMSR_trans_cons t_jnatrix_2d 

{destjnatrixJield, tx, ty signifjen, exp Jen) 

CM_f ield__id__t destjnatrixJield; 
double tx, ty; 

unsigned int signifjen; 
unsigned int exp Jen; 

void 

CMSR_tr ans_cons t_matr ix_3d 

( destjnatrixJield\ tx, ty, tz, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield; 
double tx, ty, tz; 

unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 


INCLUDE ' /usr/include/cm/cmsr-math-fort. h' 


& 


SUBROUTINE CMSR_TRANS_CONST_MATRIX_2D 

{destjnatrixJield, tx, ty, signifjen, exp Jen) 


INTEGER 

DOUBLE PRECISION 

INTEGER 

INTEGER 


destjnatrixJield 
tx, ty 
signifjen 
exp Jen 
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CMSR_trans_const_matrix_2d 

CMSR_trans_const_matrix_3d 


SUBROUTINE CMSR_TRANS_CONST_MATRIX_3D 

& ( destjnatrixJield, tx, ty, tz, signifjen, exp Jen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION tx 
DOUBLE PRECISION ty 
DOUBLE PRECISION tz 
INTEGER signifjen 

INTEGER exp Jen 


Lisp Syntax 

CMSR: trans-const-matrix-2d (dest-matrixjield tx ty 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR: trans-const-matrix-3d (dest-matrix-field tx ty tz 

&optional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the transformation matrix is to be written. Each element of 
the matrix is a floating-point value having a length of ( signifjen 
+ exp len + 1), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * ( signifjen + exp len + 1). 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * ( signifjen + exp Jen +1). 

tx A double-precision value on the front-end computer, tx is the x 

translation value to be incorporated into the transformation matrix 
in destjnatrixJield. 

ty A double-precision value on the front-end computer, ty is the y 

translation value to be incorporated into the transformation matrix 
in destjnatrixJield. 
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tz For CMSR_trans_const_matrix_3d, a double-precision value 

on the front-end computer, tz is the z translation value to be 
incorporated into the transformation matrix in destjnatrixJield. 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrix Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield. 


DESCRIPTION 

CMSR_trans_const_matrix_2d inserts the translation terms tx and ty into the ma¬ 
trix in each active processor in destjnatrixJield. 

CMSR_trans_const_matrix_3d inserts the translation terms tx, ty, and tz into the 
matrix in each active processor in destjnatrixJield. 


SEE ALSO 

CMSR_translation_matrix_2d 
CMSR_translation-matrix-3d 
CMSR_fe_translation_matrix_2d 
CMSR fe translation matrix 3d 
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CMSR_translation_matrix__2d 

CMSR_translation__matrix_3d 

Inserts fields of 2D (3D) translation terms into a transformation matrix field. 

SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_translation_matrix_2d 

( destjnatrixJield, txJield, tyJield, signifjen, exp Jen) 

CM_field._id._t destjnatrixJield; 

CM_field_id_t txJield, tyJield; 
unsigned int signifjen; 
unsigned int exp len; 

void 

CMSR_translation_matrix_3d 

(dest matrix Jield, txJield, tyJeld, tzJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJeld; 

CM_field_id_t txJeld, tyJeld, tzJeld; 
unsigned int signifjen; 
unsigned int exp Jen; 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_TRANSLATION_MATRIX_2D 

& (destjnatrixJeld, txJeld, tyJeld, signifjen, exp Jen) 

INTEGER destjnatrixJeld 
INTEGER txJeld, tyJeld 
INTEGER signifjen 
INTEGER exp Jen 
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CMSR_TRANSLATI0N_MATRIX_3D 

6 ( destjnatrixJield, txJield, tyJield, tzJield, ,signif_len, exp Jen) 

INTEGER destjnatrixJield 
INTEGER txJield, tyJield, tzJield 
INTEGER signifjen 
INTEGER exp Jen 


Lisp Syntax 

CMSR: translation-matrix-2d (dest—matrix—field tx-field ty-field 

Soptional ( signif-len 23) ( exp-len 8)) 

CMSR:translation-matrix-3d {dest—matrix Jeld tx—field ty—field tz-field 

Soptional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory 
containing a transformation matrix. Each element of the matrix is 
a floating-point value having a length of {signifjen + exp Jen + 
1), where signifjen is the length of the significant!, exp Jen is the 
length of the exponent, and 1 is the sign bit. 

The 2D matrix field contains a 3 x 3 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
9 * {signifjen + exp Jen +1). 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. The length of the entire field is 
16 * {signifjen + exp Jen + 1). 

txjeld A Paris field identifier specifying the field in CM memory 

containing the x coordinate translation value to be inserted into 
destjnatrix Jield. tx Jeld must be in the same VP set as 
destjnatrixJeld. 

txJeld is a floating-point value of length {signifjen + exp Jen + 
1 + color Jen), where signifjen is the length of the significant!, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

ty Jeld A Paris field identifier specifying the field in CM memory 

containing the y coordinate translation value to be inserted into 
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destjnatrixJeld. tyJield must be in the same VP set as 
destjnatrixJield. 

tyJield is a floating-point value of length ( signifjen + exp Jen + 
1 + color Jen), where signifjen is the length of the significant!, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

tzJeld For CMSR_translation-matrix-3d, a Paris field identifier 

specifying the field in CM memory containing the z coordinate 
translation value to be inserted into destjnatrixJeld. tzJeld 
must be in the same VP set as destjnatrix Jeld. 

tzJeld is a floating-point value of length ( signifjen + exp Jen + 
1 + color leri), where signif jen is the length of the significant!, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

signifjen The length, in bits, of the significand of the floating-point values 

in txJeld, ty Jeld, and destjnatrix Jeld. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

txJeld, ty Jield, and destjnatrixJeld. 


DESCRIPTION 

For each active processor, CMSR_translation_matrix_2d creates a two-dimen¬ 
sional translation matrix by setting the transformation matrix in dest jnatrix Jeld to an 
identity matrix and then inserting the translation terms tx Jeld and ty Jeld. 

For each active processor, CMSR_translation_matrix_3d creates a three-dimen¬ 
sional translation matrix by setting the transformation matrix in destjnatrixJeld to an 
identity matrix and then inserting the translation terms tx Jeld, ty Jeld, and tz Jeld. 

All fields must be in the current VP set. 

SEE ALSO 

CMSR_translation_const_matrix_2d 
CMSR_translation_const_matrix_3d 
CMSR_fe_translation_matrix_2d 
CMSR fe translation matrix 3d 
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CMSR__x_rotation_const_matrix_3d 

CMSR_y_rotation_const_matrix_3d 

CMSR_z_rotation_const_matrix_3d 

Inserts a specified rotation around x (y, z) into a 3D transformation matrix field. 


SYNTAX 
C Syntax 

#indude <cm/cmsr .h> 
void 

CMSR_x_rotation_const_matrix_3d 

(i destjnatrixJield, theta, signifjen, exp Jen) 

void 

CMSR_y_rotation_const_matrix_3d 

(destjnatrixJield, theta, signifjen, exp Jen) 

void 

CMSR_z__ro ta tion_cons t_matrix_3d 

( destjnatrixJield, theta, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield; 
double theta ; 

unsigned int signifjen; 

unsigned int exp Jen; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_X_ROTATION_CONST_MATRIX_3D 

& (destjnatrixJield, theta, signifjen, exp Jen) 

SUBROUTINE CMSR_Y_ROTATION_CONST_MATRIX_3D 

& (destjnatrixJield, theta, signifjen, exp Jen) 

SUBROUTINE CMSR_Z_ROTATION_CONST_MATRIX_3D 

£ (destjnatrix^field, theta, signifjen, exp Jen) 

INTEGER destjnatrixJield 

DOUBLE PRECISION theta 
INTEGER signifjen 

INTEGER exp Jen 
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Lisp Syntax 

CMSR:x-rotation-cons t-matrix-3d 

(dest-matrix-field theta 

&optional ( signif-len 23) (exp-len 8)) 

CMSR:y-rotation-const-matrix-3d 

(dest-matrix-fleld theta 

&optional ( signif-len 23) ( exp-len 8)) 

CMSR:z-rotation-const-matrix-3d 

(,dest-matrix-field theta 

&optional ( signif-len 23) ( exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the 3D transformation matrix is to be returned. 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. Each element of the matrix is a 
floating-point value having a length of ( signifjen + exp Jen + 1), 
where signifjen is the length of the significand, exp Jen is the 
length of the exponent, and 1 is the sign bit. The length of the 
entire field is 16 * ( signifjen + exp Jen +1). 

theta A double-precision value on the front-end computer, theta is the 

rotation, in radians, to be incorporated into the transformation 
matrix in destjnatrixJield. 

signifjen The length, in bits, of the significand of the floating-point values 

in destjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

destjnatrixJield. 


DESCRIPTION 

CMSR_x_rotation_const_matrix_3d, CMSR_y_rotation_const_matrix_ 
3d, and CMSR_z_rotation_const_matrix_3d create a three-dimensional rotation 
matrix in destjnatrixJield by setting the field to an identity matrix and then inserting a 
rotation of theta radians around the x, y, or z axis, respectively. 

All fields must be in the current VP set. 
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SEE ALSO 

CMSR_x_rotation__matrix_J3d 

CMSR_^y_rotation_matrix_3d 

GMSR_z_ r °tati on jEnat r ix_3d 

CMSR_rotationjnatrix_2d 

CMSR_rotation_const_matrix_2d 

CMSR_fe_rotation_matrix_2d 

CMSR_fe_x_rotation_matrix_3d 

CMSR_fe_y_rotation_jnatrix_3d 

CMSR fe z rotation matrix 3d 
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CMSR_x_rotation_matrix_3d 

CMSR_y_rotation_matrix_3d 

CMSR_z_rotation_matrix_3d 

Inserts field of rotation values around jc (y, z ) into a 3D transformation matrix field. 


SYNTAX 
C Syntax 


#include <cm/cmsr.h> 


void 

CMSR_x_rotation_matrix_3d 

(destjnatrixJield, thetaJield, signifjen, exp Jen) 

void 

CMSR_y_rotation_matrix_3d 

(destjnatrixJield, thetaJield, signifjen, exp Jen) 

void 

CMSR_z_rotation_matrix_3d 

( destjnatrixJield, thetaJield, signifjen, exp Jen) 

CM_field_id_t destjnatrixJield; 

CM_field_id_t thetaJield; 
unsigned int signifjen; 
unsigned int exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_X_ROTATION_MATRIX_3D 

& ( destjnatrixJield, thetaJield, signifjen, exp Jen) 

SUBROUTINE CMSR_Y_ROTATION_MATRIX_3D 

s ( destjnatrixJield, thetaJield, signifjen, exp Jen) 

SUBROUTINE CMSR_Z_ROTATION_MATRIX_3D 

& ( destjnatrixJield, thetaJield, signifjen, exp Jen) 

INTEGER destjnatrixJield 
INTEGER thetaJield 
INTEGER signifjen 
INTEGER exp Jen 
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Lisp Syntax 

CMSR:x-rotation-matrix-3d (dest-matrix-field theta-field 

fioptional ( signif-len 23) ( exp-len 8)) 

CMSR:y-rotation-matrix-3d ( dest-matrix-field theta-field 

(■optional (signif-len 23) (exp-len 8)) 

CMSR: z-rotation-matrix-3d (dest-matrix-field theta-field 

Soptional (signif-len 23) (exp-len 8)) 


ARGUMENTS 

destjnatrixJield A Paris field identifier specifying the field in CM memory to 
which the 3D transformation matrix is to be returned. 

The 3D matrix field contains a 4x4 homogeneous transformation 
matrix stored in row-major order. Each element of the matrix is a 
floating-point value having a length of ( signifjen + exp Jen +1), 
where signifjen is the length of the significand, exp Jen is the 
length of the exponent, and 1 is the sign bit. The length of the 
entire field is 16 * (signifjen + exp Jen + 1). 

thetaJield A Paris field identifier specifying the field in CM memory 

containing the rotation angle, in radians, to be inserted into 
destjnatrixJield. thetaJield must be in the same VP set as 
destjnatrixJield. 

thetaJield is a floating-point value of length (signifjen + exp Jen 
+ 1 + color Jen), where signifjen is the length of the significand, 
exp Jen is the length of the exponent, and 1 is the sign bit. 

signifjen The length, in bits, of the significand of the floating-point values 

in thetaJield and destjnatrixJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

theta Jield and destjnatrixJield. 


DESCRIPTION 

For each active processor, CMSR_x_rotation_matrix_3d, CMSR_y_rotation_ 
matrix_3d, and CMSR_z_rota’tion_inatrix_3d create a three-dimensional rota¬ 
tion matrix by setting the transformation matrix in destjnatrix Jield to an identity 
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matrix and then inserting a rotation of theta Jield radians around the x, y, or z axis, 
respectively. 

All fields must be in the current VP set. 

SEE ALSO 

CMSR^x^rotation^Gonat^matrix^Sd 
CMSR_y_r o ta tion_cons t_matrix_J3d 
CMSR_z_rotation_const__matrix_J3d 
CMSR__rotationjmatrix_2d 
CMSR_ro ta tion_cons t_matrix_2 d 
04SR_fe_rotation_matrix__2d 
CMSR_f e__x__r o t a t i on_ma t r ix_3 d 
CMSR_f e_y__r o t a t i on_ma t r i x_3 d 
CMSR fe z rotation matrix 3d 
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3.8 CM Color Conversion Routines 

This section documents the *Render routines that convert color vectors between color 


spaces. 

CMSR_rgb_to_cmy. 301 

CMSR_cmy_to_rgb. 301 

CMSR_rgb_to_yiq. 303 

CMSR_yi q_to_rgb. 303 

CMSR_rgb_to_hsv. 305 

CHSR_hsy_to_rgb. 305 

CMSR_rgb_to_hsl. 307 

CMSR_hsl_to_rgb. 307 
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CMSR_rgb_to_cmy 

CMSR_cmy_to_rgb 

Converts color vector fields RGB to CMY (CMY to RGB) color models. 


SYNTAX 
C Syntax 

finclude <cm/cmsr.h> 
void 

CMSR_rgb_to_cmy ( cmy_vectorJield, rgb_vectorJield, signifjen, exp Jen) 

CM_field_id_t cmy_vectorJield, rgb_vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_any_to_rgb (rgb_vectorJield, cmy_vectorJield, signifjen, exp Jen) 

CM_field_id_t rgb_vectorJield, cmyjvectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_RGB_TO_CMY 

& ( cmy_vectorJield, rgb vectorJield, signifjen, exp Jen) 

INTEGER cmy_vectorJield, rgb_vectorJield 
INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_CMY_TO_RGB 

& ( cmy_yectorJield, rgb vectorJeld, signifjen, exp Jen) 

INTEGER rgb_vectorJeld, cmy_vectorJeld 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR:rgb-to-cmy (cmy-vectorjeld rgb-vectorjeld 

fioptional ( signif-len 23) ( exp-len 8)) 
CMSR:cmy-to-rgb ( rgb-vectorjeld cmy-vectorjeld 

soptional (signif-len 23) (exp-len 8)) 
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CMSR_rgb_to_emy 

CMSR_cmy_to_rgb 


ARGUMENTS 


rgb_yectorJield 

A Paris field identifier specifying the field in CM memory 
containing the RGB color triplet. The red intensity is in the first 
element, the green intensity is in the second element, and the blue 
intensity is in the third element. Each intensity should be in the 
range of [0,1]. 

cmy_yectorJield 

A Paris field identifier specifying the field in CM memory 
containing the CMY color triplet. The cyan intensity is in the first 
element, the magenta intensity is in the second element, and the 
yellow intensity is in the third element. Each intensity should be 
in the range of [0,1]. 

Each element in these fields is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length 
of the significant!, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is 3 * ( signifjen + 
exp Jen +1). 

signifjen 

The length, in bits, of the significand of the floating-point values 
in rgbjyector Jeld and cmy vector Jeld. 

exp Jen 

The length, in bits, of the exponent of the floating-point values in 
rgb_vectorJeld and cmyvectorJeld. 

DESCRIPTION 


For each active processor in the current VP set, CMSR_rgb_to_cmy converts the RGB 
triplet in rgb_yectorJield to a CMY triplet and places the result in cmy_yector Jield. 
The relationship is 

(c,m,y) = (1,1,1) - (r,g,b) 

Similarly, for each active processor in the current VP set, catSR_cmy_to_rgb con¬ 
verts the CMY triplet in cmy_vector Jield to RGB and places the result in 
rgb_yectorJield. The relationship is 

(r,g,b) = (1,1,1) - (c,m,y) 
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CMSR_rgb_to_yiq 

CMSR_yiq_to_rgb 

Converts color vector fields from RGB to YIQ (YIQ to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_rgb_to_yiq (yiq_vectorJeld ’ rgb_vectorJield, signifjen exp Jen) 

CM_field_id_t yiqvectorJield, rgb_vector Jield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_yiq_to__rgb ( rgbjyectorJield, yiq_vectorJeld, signifjen exp Jen) 

CM_field_id_t rgb_vectorJeld, yiq_vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort. h' 

SUBROUTINE CMSRJRGBJTO_YIQ 

& (yiqjyectorJeld, rgbjyectorJeld, signifjen, exp len) 

INTEGER yiq-vectorJeld, rgbjyector Jeld 
INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_YIQJTO_RGB 

& ( rgbjyectorJeld, yiq_vectorJeld, signifjen exp Jen) 

INTEGER rgbjyector Jield, yiq_vector Jeld; 

INTEGER signifjen, exp Jen; 


Lisp Syntax 

CMSR: rgb-to-yiq (yiq-vectorJeld rgb-vectorJield 

^optional ( signif-len 23) (exp-len 8)) 
CMSR: yiq-to-rgb (rgb-vectorJeld yiq-vector Jeld 

^optional (signif-len 23) (exp-len 8)) 
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ARGUMENTS 

rgb_yector Jield A Paris field identifier specifying the field in CM memory 

containing the RGB color triplet. The red intensity is in the first 
element, the green intensity is in the second element, and the blue 
intensity is in the third element. Each of the RGB color 
components should be in the range of [0,1]. 

yiq vector Jield A Paris field identifier specifying the field in CM memory 

containing the YIQ color triplet. The Y (luminance) intensity is in 
the first element, the I (orange-cyan chromaticity) intensity is in 
the second element, and the Q (green-magenta chromaticity) 
intensity is in the third element. Each intensity should be in the 
range of [0,1]. 

Each element in these fields is a floating-point value having a 
length of ( signiflen + exp Jen + 1), where signiflen is the length 
of the significand, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is 3 * ( signif len + 
exp Jen +1). 

signifjen The length, in bits, of the significand of the floating-point values 

in rgb_vector Jield and yiqvector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

rgbjyectorJield and yiq_vector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_rgb_to__yiq converts an RGB 
triplet in rgb_vectorJield to a YIQ triplet and places the result in yiq_vector Jield. 

For each active processor in the current VP set, CMSR_y i q_to_rgb converts a YIQ 
triplet in yiq vector Jield to an RGB triplet and places the result in rgb_vectorJield. 
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CMSR_rgb_.to_.hsv 

CMSR_hsv_to_rgb 

Converts color vector fields from RGB to HSV ( HSV to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_rgb_to_hsv ( hsvvectorJield, rgbjyectorJield, signifjen, exp Jen) 

CM_field_id_t hsv_vectorJield, rgb vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_hsv_to_rgb ( rgbjvectorJield, hsv_vectorJield, signifjen, exp Jen) 

CM_£ield_id_t rgb_yectorJield, hsv_vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_RGB_TO_HSV 

fi (hsvjyectorJield, rgb_yectorJield, signifjen, exp Jen) 

INTEGER hsv_vectorJield, rgb_vectorJield; 

INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_HSV_TO_RGB 

& ( rgb_yectorJield, hsv_vectorJield, signifjen, exp Jen) 

INTEGER rgb_yectorJield, hsvjyectorJield; 

INTEGER signifjen, exp Jen; 

Lisp Syntax 

CMSR:rgb-to-hsv (rgb-vectorJield hsv-vectorJield 

fioptional ( signif-len 23) ( exp-len 8)) 
CMSR:hsv-to-rgb (hsv-vectorJield rgb-vector-field 

fioptional (signif-len 23) (exp-len 8)) 
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ARGUMENTS 

rgb_yectorJield A Paris field identifier specifying the field in CM memory 

containing the RGB color triplet. The red intensity is in the first 
element, the green intensity is in the second element, and the blue 
intensity is in the third element. Each of intensity should be in the 
range of [0,1]. 

hsv_vector Jield A Paris field identifier specifying the field in CM memory 

containing the HSV color triplet. The hue of the color is in the first 
element, the saturation is in the second element, and the value is 
in the third element. Hue should be in the range [0, 2*pi], and 
saturation and value should be in the range [0,1]. 

Each element in these fields is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length 
of the significand, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is 3 * {signifjen + 
exp Jen +1). 

signifjen The length, in bits, of the significand of the floating-point values 

in rgbjvector Jield and hsvjyector Jield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

rgb vector Jield and hsv_vector Jield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_rgb_to_hsv converts the RGB 
triplet in rgb_vector Jield to an HSV triplet and places the result in hsv_vector Jield. 
Hue will be between 0.0 and 2*pi. If s is zero, h is irrelevant and is set to zero. If v is 
zero, h and s are irrelevant and both are set to zero. 

For each active processor in the current VP set, CMSR_hsv_to_rgb converts the HSV 
triplet in hsv_vectorJield to an RGB triplet and places the result in rgh_vectorJield. 
Hue is taken modulo 2*pi. If s is zero, h is irrelevant and is set to zero. If v is zero, s and 
v are irrelevant and both are set to zero. 
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CMSR_rgb_to_hsl 

CMSR_hsl_to_rgb 


CMSR_rgb_to_hsl 

CMSR_hsl_to_rgb 

Converts color vector fields from RGB to HSL (HSL to RGB) color models. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_rgb_to_hs 1 {hsl_vectorJield, rgb_vectorJield, signifjen, exp Jen) 

CM_field_id_t hsl_vectorJield, rgb_vectorJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_hs l_to_rgb (rgb_vectorJield, hsl_vectorJield, signifjen, exp Jen) 

CM_field_id_t rgb_vectorJield, hsl_vectorJield; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_RGB_T0_HSL 

& ( hsl_vectorJield, rgbvectorJield, signifjen, exp Jen) 

INTEGER hsl_vectorJield, rgb vectorJield; 

INTEGER signifjen, exp Jen; 

SUBROUTINE CMSR_HSL_TO_RGB 

& ( rgbjyectorJield, hsl_vectorJield, signifjen, exp Jen) 

INTEGER rgbjyectorJield, hsl_vectorJield; 

INTEGER signifjen, exp Jen; 


Lisp Syntax 

CMSR: rgb-to-hsl ( rgb-vectorJield hsl-vectorJield 

fioptional ( signif-len 23) (exp-len 8)) 
CMSR:hsl-to-rgb {hsl-vectorJield rgb-vector-field 

Soptional {signif-len 23) {exp-len 8)) 
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CMSR_rgb_to_hsl 

CMSR_hsl_to_rgb 


ARGUMENTS 

rgb_vector Jield A Paris field identifier specifying the field in CM memory 

containing the RGB color triplet. The red intensity is in the first 
element, the green intensity is in the second element, and the blue 
intensity is in the third element. Each intensity should be in the 
range of [0,1]. 

hsl_vectorJield A Paris field identifier specifying the field in CM memory 

containing the HSL color triplet. The hue of the color is in the first 
element, the saturation is in the second element, and the lightness 
is in the third element. Hue should be in the range [0, 2*pi], and 
saturation and lightness should be in the range [0,1]. 

Each element in these fields is a floating-point value having a 
length of ( signifjen + exp Jen + 1), where signifjen is the length 
of the significand, exp Jen is the length of the exponent, and 1 is 
the sign bit. The length of the entire field is 3 * ( signif jen + 
exp Jen +1). 

signifjen The length, in bits, of the significand of the floating-point values 

in rgb_vector Jield and hslvectorJield. 

exp Jen The length, in bits, of the exponent of the floating-point values in 

rgb_vectorJield and hsl_vectorJield. 


DESCRIPTION 

For each active processor in the current VP set, CMSR_rgb_to_hsl converts the RGB 
triplet in rgb_vector Jield to an HSL triplet and places the result in hsl_yectorJield. 

For each active processor in the current VP set, CMSR_hsl_to_rgb converts the HSL 
triplet in hsl_vectorJield to an RGB triplet and places the result in rgb_vector Jield. 

If saturation is zero, the resulting color is a gray shade. In this case hue is irrelevant and 
is set to zero. If lightness is zero, the color is black. In this case both hue and saturation 
are irrelevant and are set to zero. 
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3.9 CM Miscellaneous Routines 

This section contains utility routines that convert between degrees and radians. 


CMSR_deg_to_rad. 310 

CMSR_rad_to_deg. 310 
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CMSR_deg_to_rad 

CMSR__rad_.to_.deg 

Converts degrees to radians (radians to degrees) for CM fields. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_deg_to_rad (dest Jeld', srcJield, signifjen, exp Jen) 

void 

CMSR_rad_to_deg (destJield, srcJield, signifjen, exp len) 

CM_field_id_t destJield; 

CM_field_id_t srcJield; 
unsigned int signifjen; 
unsigned exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-math-fort.h' 

SUBROUTINE CMSR_DEG_TO_RAD (destJield, srcJeld, signifjen, exp Jen) 
SUBROUTINE CMSR_RAD_TO_DEG (destJeld, srcJeld, signifjen, exp Jen) 

INTEGER destJeld 
INTEGER srcJeld 
INTEGER signifjen 
INTEGER exp Jen 

Lisp Syntax 

CMSR: deg-to-rad (dest Jeld src Jeld 

(optional (signif-len 23) (exp-len 8)) 

CMSR: rad-to-deg (destJeld src Jeld 

(optional (signif-len 23) (exp-len 8)) 
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ARGUMENTS 

destJield 


srcJield 


signifjen 


exp Jen 


A Paris field identifier specifying the field in CM memory to 
which the result is written, dest Jield must be in the same VP set 
as src Jield. 

A Paris field identifier specifying the field in CM memory from 
which the value to be converted is taken, src Jield must be in the 
same VP set as dest Jield. 

The length, in bits, of the significand of the floating-point values 
in dest Jield and src Jield. 

The length, in bits, of the exponent of the floating-point values in 
dest Jield and src Jeld. 


DESCRIPTION 

For each active processor, CMSR_rad_to_deg calculates the degrees equivalent to the 
number of radians specified in src Jeld and writes the result to dest Jeld. 

Conversely, for each active processor, CMSR_deg_to_rad calculates the radians 
equivalent to the number of degrees specified in src Jeld and writes the result to 
destJeld. 


SEE ALSO 

CMSR_fe_deg_to_rad 

CMSR_fe_deg_to_rad 

CMSR_fe_rad_to_deg 
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Chapter 4 

Dithering Routines 


A workstation that has only a 1-bit (black/white) display, cannot display grayscale continu¬ 
ous tone images unless they are dithered or halftoned. *Render contains several functions 
to support the halftoning of grayscale images. 

♦Render’s halftone routines convert a grayscale image of floating-point or double float¬ 
ing-point values to a 1-bit-per-pixel image suitable for displaying on a black and white 
monitor. These routines include: 

■ CMSR_u_halftone 

■ CMSR_f_halftone 

■ CMSR_u_halftone_dot_diffusion 
" CMSR_f _halftone_dot_diffusion 

■ CMSR_u_halftone_error_propagation 

■ CMSR_f_halftone_error_propagation 

In addition, two routines are provided that convert color RGB images to grayscale: 

■ CMSR_u_rgb_to_gray 
“ CMSR_f_rgb__to_gray 

Each pixel in a grayscale image represents an intensity level of gray from black to white. 
For example, an 8-bit grayscale image can display one of256 intensity levels at each pixel. 
However, in 1-bit, black and white, displays, each pixel can only be either on or off. Half¬ 
toning allows you to transfer grayscale images to 1-bit displays by using varying densities 
of black and white pixels to approximate the grayscale intensities of the original image. 

CMSR_u_halftone and CMSR_f_half tone convert a grayscale image of floating-point 
or double floating-point values, respectively, to a 1-bit-per-pixel image suitable for dis¬ 
playing on a black and white monitor. These routines are the easiest interface to the 
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♦Renders dithering routines. They use a 5 a -order dot-diffusion algorithm to halftone the 
images. 

CMSR_u_halftone_dot_dif fusion and CMSR_f_half tone_dot_dif fusion allow 
you to select the order of the dither that is to be applied to your image. The number of 
shades of gray that can be represented on the 1-bit image is determined by the order of the 
dithering. A higher-order dither increases the number of intensities but loses some image 
detail, thus exchanging geometric information for color information. 

CMSR_u_halftone_error_propagation and CMSR_f_halftone_error_propa- 
gation allow you to choose an error propagation dither instead of dot diffusion. Error 
propagation compares the grayscale value to a threshold value to determine whether the 
corresponding 1-bit pixel should be on or off. But the algorithm then also distributes the 
“error” of that decision to neighboring pixels. That is, if a pixel is turned off because its 
color value was just below the threshold, error propagation increases the likelihood that the 
neighboring pixels are turned on. The effect is to produce patterns of black and white pixels 
that approximate the grayscale intensities of the original image. 

Detailed descriptions of each of these routines follow. 
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CMSR_u_halftone 

CMSR_f_halftone 

Converts a grayscale unsigned integer (floating-point) image to a 1-bit, black and white,* 
image. 


SYNTAX 
C Syntax 

#include <cm/crasr.h> 
void 

CMSR_u_halftone ( ditheredjictureJield, picture_field,len) 

CMSR_field_id_t ditheredjictureJield, pictureJield; 

unsigned int len; 

void 

CMSR_f_halftone 

(ditheredjictureJield, pictureJield, signifjen, exp Jen) 

CM_field_id_t ditheredjpictureJield, pictureJield; 
unsigned int signiflen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-fort.h' 

SUBROUTINE CMSR_U_HALFTONE (dithered jictureJield,pictureJield, len) 

INTEGER ditheredjictureJield, pictureJield 

INTEGER len 

SUBROUTINE CMSR_F_HALFTONE 

& (ditheredjictureJield, pictureJield, signifjen, exp Jen) 

INTEGER dithered jicture Jield, pictureJield 
INTEGER signifjen, exp Jen 


Lisp Syntax 

CMSR : u-halftone (dithered-picture-fieldpicturejield len) 

CMSR: f-halftone (dithered-picture-field, picture-field, signif-len, exp-len) 
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ARGUMENTS 

ditheredjjictureJield 

A 1-bit field. The halftoned image is written to this field. 

picture Jield A field containing the image to be halftoned. 

For CMSR_u_half tone, the first 8 bits of this field are used to 
compute dithered^pictureJield. 

For CMSR_f_halftone the color values must be floating-point 
values in the range of 0 to 1. Negative values or values greater 
than 1 are clipped to this range. 

len For CMSR_u_halftone, the length of pictureJield. 

signiflen, exp Jen 

For CMSR_f_halftone, the length of the significand and 
exponent, respectively, of the floating-point values in picture_ 
field. 

NOTE: dithered_picture Jield and picture Jield must be in the same two-dimensional 
VP set. 


DESCRIPTION 

CMSR_f_halftone and CMSR_u_halftone convert a grayscale image in picture_ 
field to a 1-bit per pixel image in dithered_picture Jeld that you can display on a one- 
plane black and white monitor. 

These functions convert the color values in picture Jeld into patterns of black and 
white pixels in the destination field that approximate the gray shadings of the original 
image; darker areas have a greater density of black pixels, and lighter areas include 
more white pixels. This converted image may then be displayed on a 1-bit display. 

Note, however, that some spatial resolution is lost. The boundaries between objects in 
the converted image are less well defined than in the original, and some image detail 
may be lost. 

Specifically, CMSR_u_half tone and CMSR_f_half tone use a S^-order dot-diffu¬ 
sion algorithm to simulate 64 levels of gray intensity. See CMSR_f_halftone_dot_ 
diffusion for more detail. 

♦Render also include two functions, CMSR_u_rgb_to_gray and CMSR_f_rgb_to_ 
gray, which convert color images expressed as RGB values to grayscale images. 
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CMSR_u_halftone_dot__diff 

CMSR_f_halftone_dot_diff 


Converts a grayscale unsigned integer (floating-point) image to a 1-bit, black and white 
image using a selected dot-diffusion algorithm. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_u_halftone_dot_diff 

(i dithered_pictureJield, pictureJield, order, len) 

CM_field_id_t dithered_pictureJield, pictureJield; 
int order; 

unsigned int len; 

void 

CMSR_£_halftone_dot_diff ( dithered_pictureJield, pictureJield, order, 

signifjen, exp Jen) 

CM_field_id_t dithered_pictureJeld, pictureJeld; 

int order; 

unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-fort.h' 

SUBROUTINE CMSR_U_HALFTONE_DOT_DIFF 

& ( dithered_picture Jeld,picture Jeld, order, len) 

INTEGER dithered_pictureJeld, pictureJeld 
INTEGER order 
INTEGER len 

SUBROUTINE CMSR_F_HALFTONE_DOT_DIFF 

& ( dithered_pictureJeld, pictureJeld, order, signifjen, exp Jen) 

INTEGER ditheredjpictureJeld, pictureJeld 

INTEGER order 

INTEGER signifjen, exp Jen 
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Lisp Syntax 

CMSR:u-halftone-dot-diff 

(dithered-picture-field, picture-field, order, len) 

CMSR:d-halftone-dot-diff 

(dithered-picture-field, picture-field, order, signif-len, exp-len) 


ARGUMENTS 

dithered_pictureJield 

A 1-bit field. The halftoned image is written to this field. 

picture Jield A field containing the image to be halftoned. 

For CMSR_u_half tone_dot_diff , the first 8 bits of this field 
are used to compute dithered_picture Jield. 

For CMSR_f_halftone_dot_diff, the color values must be 
floating-point values in the range of 0 to 1. Negative values or 
values greater than 1 are clipped to this range. 

Note: dithered jpictureJield and picture Jield must be in the same two-dimensional 
VP set. 

order The desired order of the dither matrix used to halftone 

picture Jeld. Orders 0 to 5 are supported as follows: 

■ order = 0: “rounds” the picture Jeld color value to near¬ 
est black or white 

■ order = 1: picture Jeld color values reduced to 4 intensi¬ 
ties 

■ order = 2 or 3: picture Jeld color values reduced to 16 
intensities 

■ order = 4 or 5: picture Jeld color values reduced to 64 
intensities 

len For CMSR_u_half tone_dot_dif f , the length of pictureJeld. 

signifjen, exp Jen 

For CMSR_f_half tone_dot_dif f , the length of the significand 
and exponent, respectively, of the floating-point values in picture_ 
field. 
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DESCRIPTION 

CMSR_u_halftone_dot_diff and CMSR_f_halftone_dot_diff convert a 
grayscale image in picture jield to a 1-bit-per-pixel image in dithered_picture Jield 
using a dither matrix of a specified order. The converted image is suitable for display 
on a one-plane, black and white monitor. 

Grayscale images supply a single color value per pixel that maps to a color look-up 
table of gray intensity levels. For example, an 8-bit grayscale display provides 256 in¬ 
tensity levels with which to render the object. Each pixel may be set to one of those 
intensity levels, supporting a continuous range of shading. 

Single-bit, “monotone,” displays support only two settings for each pixel, on or off, 
white or black. In order to display a grayscale image on a 1-bit display, the grayscale 
intensity at each pixel must be resolved to either white or black. 

The simplest way to do this is to “round” the gray intensity to the nearest 1-bit value, 
either white or black. Pixels whose intensity is less than .5 are rounded to black, pixels 
greater than .5 are rounded to white. This produces an image with sharp contrast and 
with a considerable loss of image detail, since entire ranges of gray shadings are lost. 
This is the method used by CMSR_u__halftone_dot_diff or CMSR_£_half- 
tone_dot_dif f with an order of 0. 

Dot-diffusion methods retain more of the visual detail of the image by replacing the 
grayscale intensities in the original image with a pattern of black and white pixels; the 
value of a single grayscale pixel is combined with neighboring pixels and “diffused” 
over an area of the single-bit image. Darker areas have a greater density of black pixels, 
and lighter areas include more white pixels. The viewer perceives these areas as gray¬ 
scale intensities. 

Lower dither orders retain spatial resolution in the converted image at the expense of 
visual resolution. That is, they produce simple, high-contrast images in which the loca¬ 
tion of the objects is clearly defined but details of shading are lost. Higher-order dithers 
retain visual resolution at the expense of spatial resolution. That is, they retain more of 
the levels of shading in the original image, giving the impression of a more detailed 
image; but individual points from the original image are diffused over a larger area, 
reducing the image contrast and making the boundaries of the original objects less 
clear. 

♦Render also include two functions, CMSR_f_rgb_to_gray and CMSR_u_rgb_to_ 
gray, that convert color images expressed as RGB values to grayscale images. 
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CMSR__u__halftone_err__prop 

CMSR_f_halftone_err_prop 

Converts a grayscale unsigned integer (floating-point) image to a 1-bit image using error 
propagation. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_u_halftone_errjprop (dithered_pictureJield, picture_field,len); 

CMSR_field_id_t dithered^pictureJield, pictureJield ; 

unsigned int len ; 

void 

CMSR_f_halftone_err_prop 

(i dithered_pictureJield, pictureJield, signifjen, exp Jen) ; 

CM_field_id_t dithered_pictureJield, pictureJield ; 
unsigned int signifjen, exp Jen; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmsr-fort.h r 

SUBROUTINE CMSR_U_HALFTONE_ERR_PROP 

& ( dithered_pictureJield,pictureJield, len) 

INTEGER dithered_pictureJield, pictureJield 

INTEGER len 

SUBROUTINE CMSR_F_HALFTONE_ERR_PROP 

& {dithered_pictureJeld, picture Jield, signifjen, exp Jen) 

INTEGER dithered_pictureJield, pictureJield 
INTEGER signifjen, exp Jen 
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CMSR_u_halftone_err_prop 
CMSR_f_halftone_err_prop 


Lisp Syntax 

CMSR: f-halftone-err-prop ( dithered-picture-field, picture-field, len) 

CMSR:d-halftone-error-prop 

(dithered-picture-field, picture-field, signif-len, exp-len) 


ARGUMENTS 

dithered_pictureJield 

A 1-bit field. The halftoned image is written to this field. 

pictureJield A field containing the image to be halftoned. 

For CMSR_u_halftone_err_prop, the first 8 bits of this field 
are used to compute dithered_picture Jield. 

For CMSR_f_halftone_err_prop, the color values must be 
floating-point values in the range of 0 to 1. Negative values or 
values greater than 1 are clipped to this range. 

len For CMSR_u_hal f tone_er r_prop , the length of pictureJield. 

signifjen, exp Jen 

For CMSR_f_hal f tone_er r_pr op, the length of the significand 
and exponent, respectively, of the floating-point values in 
pictureJield. 

NOTE: dithered jpicture Jield and picture Jield must be in the same two-dimensional 
VP set. 


DESCRIPTION 

CMSR_u_halftone_err_prop and CMSR_f_halftone_err_prop convert a 
grayscale image in picture Jield to a 1-bit-per-pixel image in dithered_picture Jield 
and apply error propagation to improve the visual quality of the image. The converted 
image is suitable for display on a one-plane, black and white monitor. 

Grayscale images supply a single color value per pixel that maps to a color look-up 
table of gray intensity levels. For example, an 8-bit grayscale display provides 256 in¬ 
tensity levels with which to render the object. Each pixel may be set to one of those 
intensity levels, supporting a continuous range of shading. 
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Single bit, black and white or monotone, displays support only two settings for each 
pixel, on or off, white or black. In order to display a grayscale image on a 1-bit display, 
the grayscale intensity at each pixel must be resolved to either white or black. 

Error propagation compares the grayscale value to a threshold value to determine 
whether the corresponding 1-bit pixel should be on or off. But the algorithm then also 
distributes the “error” of that decision to neighboring pixels. That is, if a pixel is turned 
off because its color value is just below the threshold, error propagation increases the 
likelihood that the neighboring pixels are turned on. The effect is to produce patterns of 
black and white pixels that approximate the grayscale intensities of the original image. 

The error propagation applied by these functions produces visual resolution compara¬ 
ble to the 5 & -order dot diffusion applied by CMSR_u_halftone_dot_dif fusion or 
CMSR f halftone dot diffusion. 
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CMSR_u_rgb_to_gray 


CMS R_f_rg b_t o_g ray 
C M S R_u_rg b_t o_g ray 

Converts RGB floating-point (unsigned integer) data to grayscale. 


SYNTAX 
C Syntax 

#include <cm/cmsr.h> 
void 

CMSR_f_rgb_to_gray 

( grayJield, redJield', green JieldblueJield, signifjen, exp Jen) 

CM_field_id_t grayJield; 

CM_field_id_t redJield, green Jield, blueJield; 
unsigned int signifjen, exp Jen; 

void 

CMSR_u_rgb_to_gray (grayJield, redJield, green Jield, blueJield, len) 

CM_field_id_t grayJield; 

CM_field_id_t red Jield, green Jield, blueJield; 

unsigned int len; 


Fortran Syntax 

INCLUDE'/usr/include/om/cmsr-fort.h' 

SUBROUTINE CMSR_F_RGB_TO_GRAY 

& (grayJield, redJield, greenJield, blueJield, signifjen, exp Jen) 

INTEGER grayJield 

INTEGER redJield, green Jield, blueJield 

INTEGER signifjen, exp Jen 

SUBROUTINE CMSR_U_RGB_TO_GRAY 

& (grayJield, redJield, green Jield, blueJield, len) 

INTEGER grayJield 

INTEGER redJield, green Jield, blueJield 

INTEGER len 
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Lisp Syntax 

CMSR:f-rgb-to-gray 

(gray-field, red-field, green-field, blue-field, signif-len, exp-len) 
CMSR:u-rgb-to-gray (gray-field, red-field, green-field, blue-field, len) 


ARGUMENTS 

gray Jield The grayscale image is written to this field. 

red Jield, green Jield, blue Jield 

The fields containing the red, green, and blue color values to be 
converted. 

For CMSR_u_rgb_to_gray, the first 8 bits of each field are used 
to compute gray Jield. 

For CMSR_f_rgb_to_gray, the color values must be 
floating-point values in the range of 0 to 1. Negative values or 
values greater than 1 are clipped to this range. 

len For CMSR_u_rgb_to_gray, the length of redJield, green Jield, 

and blue Jield. 


signiflen, exp Jen 

For CMSR_f_half tone_err_prop, the length of the significand 
and exponent, respectively, of the floating-point values in 
redJield, green Jield, and blueJield. 

Note: The fields grayJield, redJield, green Jield, and blueJield. must all be in the 
same two-dimensional VP set. 


DESCRIPTION 

For each processor in the current VP set, CMSR_f_rgb_to_gray and CMSR_u_rgb_ 
to_gray convert the triplet of red, green, and blue color values in the fields gray Jield, 
red Jield, green Jield, and blue Jield to a single grayscale value in the field gray Jield. The 
converted image is suitable for display on a grayscale monitor or for conversion to a 
1-bit monotone image using the *Render dot-diffusion or error propagation routines. 

CMSR_f_rgb_to_gray and CMSR_u_rgb_to_gray compute the * Y’ term in the YIQ 
color model in the same way a black and white TV set turns a color signal into a bright- 
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CMS R_f_rg b_to_g ray 
CMSR_u_rgb_to_gray 


ness signal. Specifically, these functions compute a linear combination of RGB as 
follows: Y = .3 * R + .59 * G + .11 * B 
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CMSRc 

CMSR_cmy_to__rgb, 301 

CMSR_d 

CMSR__deg__to_rad, 310 
CMSR_draw_image, 66 

CMSR_f 

CMSR_f_clip_lines, 56 
CMSR_f__draw__l ine, 40 
CMSR_f_j±raw__point, 19 
CMSR_f_draw_point_3d, 23 
CMSR_f e__cmy_to_r gb, 164 
CMSR__f e_deg_t o__r ad, 173 
CMSR_fe_draw_rectangle, 69 
CMSR^f e_f__dr aw__line, 48 
CMSR_f_jdr aw_point, 30 
CMSR_fe_f_draw_point_3d, 33 
CMSR^f e_hs l__to_rgb, 170 
CMSR_fe__hsv_to_rgb, 168 
CMSR__fe_identi ty__matrix_2 d, 131 
CMSR_fe__identi ty_ma t r ix_3 d, 131 
CMSR__f e_m__copy__2 d, 133 
C^R_fe_m_copy_3d, 133 
CMSR_fe_m__determinant_2d, 135 
CMSR_fe_jn_de te rmi nan t__3 d, 135 
CMSR_f e_in_inver t_2 d, 137 
CMSR_fe_m_invert_3d, 137 
CMSR_f e_m_mul tip 1 y_J2 d, 139 
CMSR__f e_m_jnul tiply_3d, 139 
CMSR_fe_m_print_2d, 141 


CMSR_fe_m_print_3d, 141 
CMSR_fe__oblique_proj_matrix, 143 
CMSR_fe_orthojprojjmatrix, 145 
CMSR_fe_jperspective_matrix, 147 
CMSR_fe_jperspective__proj_matrix, 149 
CMSR__fe_rad__to_deg, 173 
CMSR__f e_r gb_to__cmy, 164 
CMSR_f e__r gb_to__hsl, 170 
CMSR__f e_r gb__to_hs v, 168 
CMSR__f e_r gb_t o_y i q, 166 
CMSR_fe_rotation__matrix__2d, 151 
CMSR_fe_scale_matrix_2d, 153 
CMSR_fe__scale_matrix_3d, 153 
CMSR_f e_s_dr aw_JL ine, 52 
CMSR__fe_s_draw_jpoint, 37 
CMSR_fe_translation_matrix_J2d, 155 
CMSR_fe_translation_matrix_3d, 155 
CMSR__fe_v_abs_2d, 93 
CMSR_fe_v_abs — 3d, 93 
CMSR__f e__v__ab s__squared_2 d, 95 
CMSR__fe_v_abs__s quar ed_3d, 95 
CMSR__f e_v_add__2 d, 97 
CMSR_f e__v_add__3d, 97 
CMSR_fe_v_copy_2d, 99 
CMSR_fe_v_copy__3d, 99 
CMSR__f e__v_co s_be tween_2 d, 101 
CMSR_f e_y_co s__be tween_3d, 101 
CMSR_fe_v_cross_product_3d, 103 
CMSR_fe_v_dot_product_2d, 105 
CMSR_f e_v__do t_pr oduc t_3d, 105 
CMSR__fe_view_matrix, 157 
CMSR_fe__view_proj_matrix, 159 
CMSR_f e_v_i s_zero__2d, 107 
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CMSR_f e_y_i s_z e r o_3d, 107 
CMSR_fe_v_negate_J2d, 109 
CMSR_fe_v_negate_3d, 109 
CMSR_fe_v_normalize__2d, 111 
CMSR_fe_v_normalize__3d, 111 
CMSR_fe__v__perpendicular_2d, 113 
CMSR_f e_v_perpendi cul ar_3d, 113 
CMSR_fe__v_print_2d, 115 
CMSR_fe_vj?rint_J3d, 115 
CMSR__fe_v_reflect_2d, 117 
CMSR_fe__v_reflect__3d, 117 
CMSR_fe_v_scaleJ2d, 119 
CMSR_f e__v_s cal e_3d, 119 
CMSR_f e_v_sub trac t_J2 d, 121 
CMSR__fe_v_s\abtract_3d, 121 
CMSR_f e__v__trans f orm__2 d, 123 
CMSR_f e__v__trans f orm__3d, 123 
CMSR__f e__v__tr ansmi t__3d, 126 
CMSR__f ©_x__r o t a t ion_ma t r i x__3 d, 161 
CMSR_fe_yiq^to_rgb, 166 
CMSR_f rotationjma tr ix__3d, 161 

CMSR_f e_z__r o ta tion_ma t r ix_J3 d, 161 
04SR_f_halftone, 315 
CMSR_f_halftone__dot_diff 5 317 
CMSR_f_half tone_err_jprop, 320 
CMSR_f_ r gb__t°__g r ay, 323 

CMSR_h 

CMSRhsl_to_rgb, 307 
CMSR_hsv_to_rgb, 305 

CMSR_i 

CMSR_identity__matrix_J2d, 246 
CMSR^identi ty_ma tr ix__3d, 246 
CMSR_initialize__z_Jbuf fer, 17 

CMSR_m 

CMSR_m_alloc_heap_f ield_2d, 248 
C^R_m_al loc_Jieap_f ield_3d, 248 
CMSR_m_alloc_stack_field_2d, 250 
CMSR_m_al loc_stack_field_3d, 250 
CMSR_m_copy__2d, 252 


CMSR_m_copy_3d, 252 
CMSR_jn__copy_const_J2d, 254 
CMSR_m__copy__cons t_3d, 254 
CMSR_m_determinant__2d, 256 
CMSR_jn_determinant__3d, 256 
CMSR_m__f ie 1 d__leng th, 258 
CMSR_m_invert__2d, 260 
CMSR_m_invert__3d, 260 
CMSR_m__multiply_2d, 262 
CMSR__m__multiply_3d, 262 
CMSR__m__mul tiply_cons t_2d, 265 
CMSR_m_mul tiply__cons t__3d, 265 
CMSR_in_p r i n t_2d, 268 
CMSR__m_j> r i n t_3d, 268 
CMSR_m_r ead_f r om_pr oces sor_J2d, 270 
CMSR_ mj read — f rom_processor_3d, 270 
CMSR_m__r ef_2d, 273 
CMSR__m_ref_3d, 273 
C^Rjm_write_tojprocessorJ2d, 275 
CMSR_m__write_to_j>rocessor_3d, 275 

CMSR_r 

CMSR__rad_to_deg, 310 
CMSR_read_array__from_field, 79 
CMSR__read__array__from_field__l, 82 
CMSR_rgb_to_cmy, 301 
04SR_rgb_to_hsl, 307 
CMSR__rgb_to_hsv, 305 
CMSR_rgb__to_jyiq, 303 
CMSR_rotation_const_matrix_2d, 278 
C^R_rotationjmatrix_2d, 280 

CMSR_s 

CMSR_scale — constjmatrix_2d, 282 
C^R_scale_constjnatrix__3d, 282 
C^R_scale_matrix_2d, 285 
CMSR_scalejmatrix_3d, 285 
CMSR_s_clip_lines, 59 
CMSR___s_draw_line, 44 
CMSR_s_drawjpoint, 27 
CMSR_s jdraw_sphere, 62 
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CMSRJ 

CMSR_J:rans_constjnatrix_2d, 288 
CMSR_trans_const_matrix_3d, 288 
CMSR — translation^matrix^2d, 291 
CMSR_translation_matrix__3d, 291 

CMSR_u 

CMSR__u_hal f tone, 315 
CMSR__u_hal f tone_do t_di f f, 317 
CMSR__u__hal f tonemerr_prop, 320 
CMSR__u_rgb__to__gray, 323 

CMSR_v 

CMSR _ v _ abs _ 2d ’ 177 
CMSR_v_abs_3d, 177 

CMSR_v_abs__squared_2d, 179 
CMSR_v_ab s_s qua re d_J3 d, 179 
CMSR_v_add_2 d, 181 
CMSR_v_add__3d, 181 
CMSR_v_al loc__heap__f ield_2 d, 183 
CMSR_v_al l° c __h ea p__f ie ld_3d, 183 
CMSR__v__alloc__s tack__f ield__2d, 185 
CMSR_v__allo c _ s t ac k__fi e ld_3d, 185 
CMSR_v_copyJ2 d, 187 
CMSR_v_copy_3d, 187 
CMSR_vj 2 opy_cons t_2 d, 189 
CMSR__v__copy__cons t_3d, 189 
CMSR__v__co s_be twe en_J2 d, 192 
CMSR__v_co s_be tween__3d, 192 
CMSR_ v __ cr o s s jp r oduo t_3 d, 195 
CMSR_v_do t_pr oduc t__2 d, 197 
CMSR_v_do t__pr oduc t__3 d, 197 
CMSR_v_f ield^length, 200 
CMSR_v_i s__zero_2d, 202 
CMSR__v_is_zero_3d, 202 
CMSR_v_negate_2d, 204 
CMSR__v_negate_3d, 204 
(34SR_v_normali ze_2d, 207 
CMSR_v_normalize_3d, 207 
CMSR__v_p e rpendicul ar_2d, 210 
CMSR^yjpe rpendi cul ar__3 d, 210 


CMSR_v_printed, 213 
CMSR_v_print_3d, 213 
CMSR_v__r e ad__f rom_proce s s or__2 d, 215 
CMSR_v_read__f rom_processor__3d, 215 
CMSR_v_reflect_2d, 218 
CMSR_v__reflect_J3d, 218 
CMSR_v_ref_x, 221 
CMSR__v__re f_y, 221 
CMSR_v_ref__z, 221 
CMSR_v_scale_2d, 223 
CMSR__v__scale_3d, 223 
CMSR_v__scale__const_2d, 226 
CMSR__v_scale__cons t__3d, 226 
CMSR__v__subtract_2d, 229 
CMSR__v__subtract_3d, 229 
CMSR_v__t r ansf orm_2d, 232 
CMSR__v__t r ansform_3d, 232 
CMSR__v__t r ansform_const_2d, 235 
CMSR__v_transform_cons t_3d, 235 
CMSR__v_tr ansmi t_3d, 238 
CMSR__v_wr i te_to_jproces sor__2d, 241 
CMSR__y_wr i te_to__proces sor_J3d, 241 

CMSRw 

CMSR_wr i te_array_to_f i e 1 d, 71 
CMSR__write__array_J:o__field_l, 74 

CMSR_x 

CMSR__x_rotation_const__matrix__3d, 294 
CMSR_x_rotation_jnatrix_J3d, 297 

CMSR_y 

CMSR_jyig_to_rgb, 303 

CMSR_^y_ro ta tion__cons t_matrix__3d, 294 

CMSR_jy__rotation__matrix__3d, 297 

CMSR_z 

CMSR_z__rotation__const_matrix_3d, 294 
CMSR_z_rotation_matrix_3d, 297 
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2d 

CMSR__f evident! tyjma tr ix__2 d, 131 
CMSR_f e_m__copy_2 d, 133 
CMSR__f e_m_de te rmi nan t__2 d, 135 
CMSR_f ejtn_inve r t_2 d, 137 
CMSR_f e_mjmul t iply_2 d, 139 
CMSR_fejnajprint_2d, 141 
CMSR_f e_rota tion_matrix_2 d, 151 
CMSR_fe_scale_matrix_2d, 153 
CMSR__f outran s 1 ation_ma t r ix__2 d, 155 
CMSR_fe_v_absj2d, 93 
CMSR_f e_v__abs__s quar ed__2d, 95 
CMSR_fe_v__add_2d, 97 
CMSR_fe_v_copy_J2d, 99 
CMSR__f e__v_co s_jbe twe e n_2 d, 101 
CMSR__f e_v_do t_jpr oduc t_2 d, 105 
CMSR_fe_vji.s_zero_2d, 107 
CMSR_f e_v_ne ga t e__2 d, 109 
CMSR_f e_y__normali ze__2d, 111 
CMSR_f e_v_pe rpendi cular_2 d, 113 
CMSR_f e_v_pr in t__2 d, 115 
CMS R_f e_v_r e flee t_2 d, 117 
CMSR_fe__v_scale_2d, 119 
CMSR_f e_v_sub tr ac t_2 d, 121 
CMSR_f e__v__tr an s f orm_2 d, 123 
CMSR_identity_matrix_2d, 246 
CMSR_m_alloc_heap_fieldJ2d, 248 
CMSR__m_al 1 oejst ack_JE ie 1 d_2d, 250 
CMSR_m_copy__2d, 252 
CMSR_m__copy_const_2d, 254 
CMSR_m_dete rminant_2d, 256 


CMSR_m_invert_2d, 260 
OdSRjmjnaiil tiply_J2d, 262 
CMSR__m_mul tiply_cons t__2d, 265 
CMSR__m_p r int__2d, 268 
CMSR_m_read_f rom_proces sor_2d, 270 
CMSR__m_jref_2d, 273 
CMSRjm_wri te_tojproces sor__2d, 275 
CMSR__rotation__const_matrix__2d, 278 
CMSR^rotation^matrix^2d, 280 
CMSR_scale_const_matrix_2d, 282 
CMSR^scale^matrix^d, 285 
CMSR__trans_const_matrix_j2d, 288 
CMSR_translation_matrix__2d, 291 
CMSR_v_ab s__2 d, 177 
CMSR__v__ab s_s quar ed_2 d, 179 
CMSR_v_add_2d, 181 
CMSR___v_ai loc_heap__f ield__2d, 183 
CMSR_v_alloc_ stack_field_2d, 185 
CMSR__v__copy__2 d, 187 
CMSRjv_copy_const_2d, 189 
CMS R__v__c° s__be tween_J2 d, 192 
CMS R_v_do t_jpr oduc t_2 d, 197 
CMSR__v_i s_jzero__2d, 202 
CMSR__v_negate_2d, 204 
CMSR__jv_normalize_2d, 207 
GMSR_vjperpendicular > 2d 9 210 
GMSR_y_p r int — 2d, 213 
CMSR__v__read_fromjprocessor_2d, 215 
CMSR_v_reflect_2d, 218 
C*dSR_v_scale__2d, 223 
CMSR__v_scale_const_2d, 226 
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CMSR_v_subtract_2d, 229 
CMSR_v__transform_2d, 232 
CMSR_v_tr ans f orm_const_2d, 235 
CMSR_y_wr ite_to_j?rocessor__2d, 241 

3d 

CMSR_f_drawjpointJ3d, 23 
CMSR_fe_f__drawjpoint__3d, 33 
C^R_fe_identity_matrix_3d, 131 
CMSR_fe_m_copy_3d, 133 
CMSR_fejm__determinant_3d, 135 
CMSR_fe_m_invert_3d, 137 
CMSR_f e_m_mul t iply_3d, 139 
CMSR_fe_mjprint__3d, 141 
CMSR__fe_scale_matrix__3d, 153 
CMSR_fe_translation__matrix_3d, 155 
CMSR_fe_v_abs_3d, 93 
CMSR_fe_v_abs_squared_3d, 95 
OMSR_fe_v_add_3d, 97 
CMSR_fe__v_copy_3d, 99 
CMSR_f e_v_co s_be tween__3d, 101 
CMSR__f e_v_cr o s s_jpr oduc t_3d, 103 
CMSR_f e_v_do t_pr oduc t_3d, 105 
CMSR_fe_v_is_zero_3d, 107 
GMSR -_ f e_v_n e gate__ 3d ? 109 
CMSR_fe_v_normalize_3d, 111 
CMSR_fe_vjpezpendicular_3d, 113 
CMSR_fe_vjprint_3d, 115 
CMSR_fe_v_reflect_3d, 117 
CMSR_fe_v_scale_3d, 119 
CMSR_fe_v_s\ibtract_3d, 121 
CMSR^f e__v_trans f orm__3d, 123 
CMSR__fe__v_transmit_3d, 126 
CMSR^fe^x^rotation^matrix^Sd, 161 
CMSR__fe_y_rotation_jnatrix_3d, 161 
CMSR__fe_z_rotation_jnatrix_3d, 161 
CMSR_identity_matrix_J3d, 246 
CMSRjtn^al loc_heap_£ield_3d, 248 
CMSR_m_a11 o c__s t a ck_fi e X d_3 d, 250 
a4SR_m_ c °py_3d, 252 
CMSR_m_copy_const_3d, 254 
CMSRjm__d e te rminan t_3d, 256 


CMSR_jn__invert_3d, 260 
CMSR_jn_mul tiply_J3d, 262 
CMSR__ra_mul tiply__cons t_3d, 265 
CMSR _ m -J >ri nt_3d, 268 
CMSR_m_ re ad_f rom_proce s s or__3d, 270 
CMSRjajce£_3d, 273 
CMSR_m_write___to_processor_3d, 275 
CMSR_scale_const_matrix___3d, 282 
CaMSR^scale^matrix^Sd, 285 
CMSR__trans___const_matrix_3d, 288 
CMSR_translation__matrix_3d, 291 
CMSR_v_abs_3d, 177 
CMSR_v_abs__s quared_3d, 179 
CMSR_v_add_3d, 181 
CMSRjr_allocJi&ap__£ield_3d, 183 
GMSR_v_ailoc_stack__field__3d, 185 
CMSR_v___copy__3 d, 187 
CMSR_v_copy_const_3d, 189 
CMSR__v_cosJbe tween_3d, 192 
CMSR_v__cros s_product__3d, 195 
GMSR_v_do *t_jpr oduc t__3d, 197 
CMSR__v_i s_zer o_3d, 202 
CMSR_v_n e gate_3d, 204 
CMSR__v__normalize_3d, 207 
CMSR_vjp er p en di c ular_3d, 210 
CMSR_v_p r i n t — 3d, 213 
CMSR_v_read_fromjprocessor_3d, 215 
CMSR_v_ref lect_3d, 218 
CMSR_yjscale_3d, 223 
CMSR__v_scale^const_3d, 226 
CMSR__v_subti:a c t_3d, 229 
CMSR__v_transform__3d, 232 
CMSR_v__t rans f or m_ c ° n st__3d, 235 
CMSR___v__transmi t_3d, 238 
CMSR_v_write_tojprocessor_3d, 241 
CMSR_x_r ota tion_cons t_ma tr ix_3d, 294 
CMSR_x_rotation_matrix_3d, 297 
CMSR_jy__ r °tation_const_ma tr ix_3d, 294 
CMSR__y_ r otati°njoaat r ix_3d, 297 
CMSR_z_rotation_const_matrix_3d, 294 
CMSR_z_rotation_matrix__3d, 297 
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abs 

CMSR_fe_v_abs_2d, 93 
CMSR_fe_v_abs_3d, 93 
CMSR__fe_v_abs_squared_2d, 95 
CMSR^fe_v_abs__s quar ed_3d, 95 
CMSR__v_abs_2 d, 177 
CMSR_v_abs__3d, 177 
CMSR_v__abs_s quared_J2 d, 179 
CMSR_v_abs__s quar ed_3 d, 179 

add 

CMSR_f e_v_add_2d, 97 
CMSR_fe_v_add_3 d, 97 
CMSR_v_add_2d, 181 
CMSR_v_add_3d, 181 

alloc 

CMSR_m_alXoc_heap_fieXd_2d, 248 
CMSRjtt_all° c Jheap_field_3d, 248 
CMSR_jn_al1 oc__stack__f ie ld_2d, 250 
CtteR_mjzlloc_stackJEi&ldJ3d, 250 
CMSR_v_al loc_heap_f ield__2d, 183 
CMSR_v_alloc__heap__f ield_J3d, 183 
CMSR_v__alloc_stack_field_2d, 185 
CMSR_v_alloc_stack__field_3d, 185 

array 

CMSR_read_ar r ay_f r om__f ieId, 79 
CMSR_read_ar ray_f rom_f ieldJL, 82 
CMSR__wri te_array_to_f ie Id, 71 
CMSR_write_array_to — field_l, 74 

clip 

CMSR_f_clip_lines, 56 
CMSR_js_cl ip__l ine s, 59 

cmy 

CMSR_cmy_jto_rgb, 301 
CMSR_£ e_cmy_t o_r gb, 164 
CMSR_fe_rgb__to_cmy, 164 


CMSR_j:gb_to_cmy, 301 

const 

CMSR_m__copy___const_2d, 254 
CMSR_m_copy_const_3d, 254 
CMSR__m__mu 1t ip ly__con31__2d, 265 
CMSR^mjmultiply__cons t_3d, 265 
CMSR^rotation^const^matrix^d, 278 
CMSR_scale_const_matrix_2d, 282 
CMSR_scale_constjmatrix__3d, 282 
Q4SR_trans_constjnatrix_J2d, 288 
CMSR_trans_const_matrix_3d, 288 
CMSR_v_copy__cons t__2 d, 189 
CMSR__v__copy_cons t_3d, 189 
CMSRjscale_const_2d, 226 
CMSR__v_scale__const__3d, 226 
CMSRa v_transform_const — 2d, 235 
CMSRjv_transform_const__3d, 235 
CMSR_x_r o tation__cons t__matrix__3d, 294 
CMSR_jr_rotation_const__matrix_3d, 294 
CMSR__z__rotation__const__matrix_3d, 294 

copy 

CMSR__f e_m_copy__2 d, 133 
CMSR___fe_m_copy__3d, 133 
CMSR__f e__v_copy_2 d, 99 
CMSR_fe_v_copy_3d, 99 
CMSR_m_copy__2d, 252 
CMSR__m__copy_J3d, 252 
C^Rjn_copy_const_2d, 254 
CMSRjn_copy_const_3d, 254 
CMSR_v_copy_2d, 187 
CMSR_v_copy__3d, 187 
CMSR__v__copy_cons t_2d, 189 
CMSR_v_copy__cons t_3d, 189 

cos_between 

CMSR_fe_v_cos_jDetween__2d, 101 
CMSR_f e_v_co s__be tween_3d, 101 
CMSR__v_co s__be tween_2 d, 192 
CMSR__v__co s_be tween_3d, 192 
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cross_product 

CMSR_fe_v_crossjproduct_3d, 103 
CMSRjr^cr o s s_pr oduc t_3 d, 195 

deg 

CMSRjdeg_to_rad, 310 
04SR_fe_deg_to_rad, 173 
CMSRJ?e_rad_to_deg, 173 
CMSR_j:ad_to_deg, 310 

determinant 

CMSR_f e_m_de terminan t_2 d, 135 
C^R_fe_m_determinant_3d, 135 
CMSR_m_determinant_2d, 256 
CMSR__m_determinant_3d, 256 

dot_diff 

CMSR_f Jhal f tone_do t_di f f , 317 
CMSR^uJhalftone__dot_diff, 317 

dot_product 

CMSR_fe_v_dot_product_2d, 105 
CMSR__fe_v__dot_product__3d, 105 
CMSR_v_dot_product_2d, 197 
CMSR_vjdot_product_3d, 197 

draw 

CMSRjdraw_image, 66 
CMSR_f_draw_l ine, 40 
04SR_f_draw_jpoint, 19 
GMSR_f_draw_point_3d, 23 
CMSR_fe_draw_rectangle, 69 
CMSR_f e_f_dr aw__line, 48 
CMSR_fe_f jdraw_point, 30 
CMSR_feJEjdrawjpoint_3d, 33 
CMSR__fe_s_draw_line, 52 
CMSR_fe_s_draw_point, 37 
CMSR_ajdrawJL ine, 44 
CMSR_s_draw_point, 27 
CMSR_s_draw_sphere, 62 
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err_prop 

CMSR__f_Jial f tone_er r_prop, 320 
CMSR_u_ha 1 f tone_e r r_j>r op, 320 

_f_ 

CMSR_f_clip__lines, 56 
CMSR_f__draw_l ine, 40 
CMSR_f_draw_jpoint, 19 
CMSR_f_draw_jpoint__3d, 23 
CMSR__f e_fjdr aw_line, 48 

CMSR__f e_f___draw_jpoint, 30 

CMSR_fe_f_draw_jpoint__3d, 33 
CMSR_f_halftone, 315 
CMSR_f _ha 1 f tone__do t__di f f, 317 
CMSR_f__hal f tone_err_j>rop, 320 
CMSR__f__rgb__to__gray, 323 

fe 

CMSR_f e__rgb__to__hs v, 168 
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